Advantages to authoring in a topic based environment
*. More efficient
*. Structure helps produce better content
*. Takes advantage of new technologies for delivering content
I plan to share the best way to
*. Assess your current situation
*. Plan for your future and
*. Execute to the plan
After the presentation, you will:
*. Understand what topic–based writing is and its advantages
*. Follow best–practices for organizing new material into topic–based content
*. Understand the place of XML and DITA and how they may relate to your needs
Making The Move To Information ArchitectureScott Abel
Presented at DocTrain East 2007 Conference by Alan Houser, Group Wellesley -- Many documentation departments use loosely-defined or ad hoc standards for developing and delivering technical content. In many organizations, writers are judged by the volume of content that they produce. The larger the manual or help system, the more effective the writer. A fatter manual is considered to be a better manual.
In the face of todays increasingly challenging business requirements, including increasing information re-use and decreasing time-to-market, these ad hoc methodologies and old-fashioned standards quickly break down. There is no positive correlation between page or topic count and usability. Higher page or topic counts mean higher maintenance, translation, and production costs. Furthermore, information developed without a formal information architecture is difficult to manage, difficult to publish, and difficult to re-use.
To meet today’s business requirements, many organizations are adopting formal information architectures. A formal information architecture can bring many benefits, including increased writer efficiency, increased documentation usability, increased information re-use, and decreased cost of production. The most successful of these architectures embody the following concepts:
* they are based on a tested communication strategy (in the case of DITA, the minimalist documentation strategy)
* they include a formal analysis of the product or service being documented (e.g., a task analysis)
* they define multiple information types
* they define a way to define collections of those information types
What does an information architecture lookӔ like? How does using an information architecture differ from ad hoc information development strategies? We will see how one popular information architecture (DITA) defines both topics and topic collections.
We will also discuss effective strategies for adopting a formal information architecture, and for migrating legacy content to a formal information architecture. Although examples will be based on DITA, concepts will apply to any information architecture or structured authoring environment.
Introduction To Information Modeling With DITAScott Abel
Presented at DocTrain East 2007 Conference by Alan Houser, Group Wellesley -- Through effective task analysis and information modeling, organizations can maximize the usability of their technical documentation while minimizing the required development and maintenance effort. During this interactive workshop, students will learn the principles of minimalist documentation, how to perform an effective task and topic analysis, approaches to migrating legacy documentation to DITA or other information models, and methods for mapping content to pre-defined information types. We will also use software tools to assist in performing topic analysis. While this workshop will use DITA information models as examples, the workshop will provide value for anybody who needs to move to a structured authoring environment and improve the usability and maintainability of their technical documentation.
In many organizations, writers are judged by the volume of content that they produce. The larger the manual or help system, the more effective the writer. A fatter manual is considered to be a better manual.
From the users perspective, however, fatter does not mean better. There is no positive correlation between page or topic count and usability. Large documentation sets may be intimidating and are likely to present usability issues. Furthermore, higher page or topic counts mean higher maintenance, translation, and production costs.
The minimalist documentation strategy provides a way to design and deliver highly usable documentation while minimizing the amount of content that must be developed, maintained, and produced to support a product or service. The increasingly-popular DITA information architecture is based on the concepts of minimalist documentation.
During this workshop, we will learn the principles of minimalist documentation, and how minimalist documentation strategies meet both user needs and business needs. We will learn how to design minimalist documentation using the DITA information architecture. We will interactively experience the important prerequisite of task and topic analysis for creating well-designed, highly usable minimalist documentation sets.
We will also demonstrate the use of software tools to support topic analysis. In an interactive session, we will use the IBM Task Modeler to develop a task analysis for a product or service. The instructor will demonstrate how to use the IBM Task Modeler to automatically generate DITA map files and prototype DITA-based output.
Advantages to authoring in a topic based environment
*. More efficient
*. Structure helps produce better content
*. Takes advantage of new technologies for delivering content
I plan to share the best way to
*. Assess your current situation
*. Plan for your future and
*. Execute to the plan
After the presentation, you will:
*. Understand what topic–based writing is and its advantages
*. Follow best–practices for organizing new material into topic–based content
*. Understand the place of XML and DITA and how they may relate to your needs
XML for Humans: Non-geek Discussion of a Geek-chic TopicPublishing Smarter
This session, presented at the Editors Conference in Toronto, on June 8, 2014, introduces you to the basics of XML, explaining what it is, how it is used, and why it benefits people who write and edit.
While THEY may love to work with code, the goal was to put as much of this into plain language for US as possible. I think it succeeded.
Participants could learn how clear and concise content can be created (and managed) in an XML workflow. At the end of the session they had enough knowledge to speak about XML with confidence.
During the session detailed slides were presented and discussed. A packed room attended and participated (the session featured a lot of great questions and answers) over the span of an hour.
DITA PUBLISHING: The True Cost of Taking your DITA Content OnlineWebWorks
The aim of this paper is to compare the true cost of ownership associated with publishing DITA-XML content using the DITA Open Tool Kit and the WebWorks ePublisher Platform.
Making The Move To Information ArchitectureScott Abel
Presented at DocTrain East 2007 Conference by Alan Houser, Group Wellesley -- Many documentation departments use loosely-defined or ad hoc standards for developing and delivering technical content. In many organizations, writers are judged by the volume of content that they produce. The larger the manual or help system, the more effective the writer. A fatter manual is considered to be a better manual.
In the face of todays increasingly challenging business requirements, including increasing information re-use and decreasing time-to-market, these ad hoc methodologies and old-fashioned standards quickly break down. There is no positive correlation between page or topic count and usability. Higher page or topic counts mean higher maintenance, translation, and production costs. Furthermore, information developed without a formal information architecture is difficult to manage, difficult to publish, and difficult to re-use.
To meet today’s business requirements, many organizations are adopting formal information architectures. A formal information architecture can bring many benefits, including increased writer efficiency, increased documentation usability, increased information re-use, and decreased cost of production. The most successful of these architectures embody the following concepts:
* they are based on a tested communication strategy (in the case of DITA, the minimalist documentation strategy)
* they include a formal analysis of the product or service being documented (e.g., a task analysis)
* they define multiple information types
* they define a way to define collections of those information types
What does an information architecture lookӔ like? How does using an information architecture differ from ad hoc information development strategies? We will see how one popular information architecture (DITA) defines both topics and topic collections.
We will also discuss effective strategies for adopting a formal information architecture, and for migrating legacy content to a formal information architecture. Although examples will be based on DITA, concepts will apply to any information architecture or structured authoring environment.
Introduction To Information Modeling With DITAScott Abel
Presented at DocTrain East 2007 Conference by Alan Houser, Group Wellesley -- Through effective task analysis and information modeling, organizations can maximize the usability of their technical documentation while minimizing the required development and maintenance effort. During this interactive workshop, students will learn the principles of minimalist documentation, how to perform an effective task and topic analysis, approaches to migrating legacy documentation to DITA or other information models, and methods for mapping content to pre-defined information types. We will also use software tools to assist in performing topic analysis. While this workshop will use DITA information models as examples, the workshop will provide value for anybody who needs to move to a structured authoring environment and improve the usability and maintainability of their technical documentation.
In many organizations, writers are judged by the volume of content that they produce. The larger the manual or help system, the more effective the writer. A fatter manual is considered to be a better manual.
From the users perspective, however, fatter does not mean better. There is no positive correlation between page or topic count and usability. Large documentation sets may be intimidating and are likely to present usability issues. Furthermore, higher page or topic counts mean higher maintenance, translation, and production costs.
The minimalist documentation strategy provides a way to design and deliver highly usable documentation while minimizing the amount of content that must be developed, maintained, and produced to support a product or service. The increasingly-popular DITA information architecture is based on the concepts of minimalist documentation.
During this workshop, we will learn the principles of minimalist documentation, and how minimalist documentation strategies meet both user needs and business needs. We will learn how to design minimalist documentation using the DITA information architecture. We will interactively experience the important prerequisite of task and topic analysis for creating well-designed, highly usable minimalist documentation sets.
We will also demonstrate the use of software tools to support topic analysis. In an interactive session, we will use the IBM Task Modeler to develop a task analysis for a product or service. The instructor will demonstrate how to use the IBM Task Modeler to automatically generate DITA map files and prototype DITA-based output.
Advantages to authoring in a topic based environment
*. More efficient
*. Structure helps produce better content
*. Takes advantage of new technologies for delivering content
I plan to share the best way to
*. Assess your current situation
*. Plan for your future and
*. Execute to the plan
After the presentation, you will:
*. Understand what topic–based writing is and its advantages
*. Follow best–practices for organizing new material into topic–based content
*. Understand the place of XML and DITA and how they may relate to your needs
XML for Humans: Non-geek Discussion of a Geek-chic TopicPublishing Smarter
This session, presented at the Editors Conference in Toronto, on June 8, 2014, introduces you to the basics of XML, explaining what it is, how it is used, and why it benefits people who write and edit.
While THEY may love to work with code, the goal was to put as much of this into plain language for US as possible. I think it succeeded.
Participants could learn how clear and concise content can be created (and managed) in an XML workflow. At the end of the session they had enough knowledge to speak about XML with confidence.
During the session detailed slides were presented and discussed. A packed room attended and participated (the session featured a lot of great questions and answers) over the span of an hour.
DITA PUBLISHING: The True Cost of Taking your DITA Content OnlineWebWorks
The aim of this paper is to compare the true cost of ownership associated with publishing DITA-XML content using the DITA Open Tool Kit and the WebWorks ePublisher Platform.
Content creation, reuse, and publishing to everyone on every device (WritersUA)Publishing Smarter
Timing is everything. It's crucial to quickly create content for multiple audiences, manage reuse effectively, and publish to an audience that needs: the right information, at the right time, in the right format. You can follow up and in a hands-on way you: create content for multiple audiences, in seconds generate dynamic HTML5 content, do so at the click of a button
Text-rich, illustration-heavy, table-filled, overly-hyphenated manuals and docs sit on the shelf and never get read.
Today, we read information in the format we want, on whatever device we want, and with just enough information to support what we need to do.
Learn more about topic-based writing, what it is and what it can do for your approach to documentation.
Any device, any time, any format.
Painless XML Authoring?: How DITA Simplifies XMLScott Abel
Presented at DocTrain East 2007 by Bob Doyle, DITA Users -- This introduction to XML Authoring will acquaint you with over fifty tools aimed at structuring content with DITA. They are not just DITA-compliant authoring tools (editors) for writers. They also include content management systems (CMS), translation management systems (TMS), and dynamic publishing engines that fully support DITA. You will also need to know about tools that convert legacy documents to DITA and help to design stylesheets for DITA deliverables. The best DITA tools for technical communicators implement the DITA standard while hiding all the complexity of the underlying XML (eXtensible Markup Language).
As a tech writer and not a tech, you should be able to forget about XML - except to know that you are using it (DITA is XML) and that it consists of named content elements (or components) with attributes. You need to know enough about the content elements so you can reference (conref) them for reuse. You need to know about their attributes so you can filter on them for conditional processing. And you should appreciate that because components are uniquely identifiable they lend themselves perfectly to automated dynamic assembly using a publishing engine.
We will describe how you can get started with structured writing without knowing XML or installing anything.
The promise of topic-based structured authoring is not simply better documentation. It is the creation of mission-critical information for your organization, written with a deep understanding of your most important audiences, that can be repurposed to multiple delivery channels and localized for multilingual global markets. You are not just writing content, you are preparing the information deliverables that enhance the value of your organization in all its markets.
To do that well, you must understand the latest tools in structured writing that are revolutionizing corporate information systems - today in documentation but tomorrow throughout the enterprise, from external marketing to internal human resources. Whether you are trying to push a new product into a new market or are “onboarding” a new employee, the need for high quality information to educate the customer or train the new salesperson is a challenge for technical communicators. You need to think outside the docs!
The key idea behind Darwin Information Typing Architecture is to create content in small chunks or modules called topics. A topic is the right size when it can stand alone as meaningful information. Topics are then assembled into documents using DITA maps, which are hierarchical lists of pointers or links to topics. The pointers are called “topicrefs” (for topic references).
Think of documents as assembled from single-source component parts. Assembly can be conditional, dependent on properties or metadata “tags” you attach to a topic. For example, the “audience” property might be “beginner” or “advanced.”
At a still finer level of granularity, individual elements of a topic can also be assigned property tags for conditional assembly. More importantly, a topic element can be assigned a unique ID that makes it a content component reusable in other topics.
As you will learn, DITA is a leading technology for “component content management,” which multiplies the value of your work. You need to leverage DITA and structured content to multiply your income.
Gone through articles and presentations on the web and got a half-baked understanding of the Darwin Information Typing Architecture (DITA)?
Refer to my DITA Quick Start presentation for the 2007 STC India Conference to learn to evaluate, plan and start implementing DITA.
In this presentation, you will learn about the following:
o Structured authoring and XML
o Key DITA concepts: topics, maps, specialization
o DITA architecture and content model
o Authoring in topics
o Organizing content using DITA maps
o Creating relationship tables
o Conditional text and reuse in DITA
o Metadata support in DITA
o DITA tools, standards and processes
o Publishing with the DITA Open Toolkit
By now, you have heard how important structured content is. But, maybe you poked around with something like DITA and were baffled by the complexity. Or, maybe you still aren’t sure what XSLT stands for. This workshop will take participants back to the basics, to provide a foundation for higher-level concepts that have taken hold of our industry. Topics will include:
- What XML looks like, what it does, and how to create it.
- How to define a structure model, including whether to use a - DTD, Schema, etc.
- What XSLT looks like, what it does, and how to make it work.
- What DITA and DocBook really are and whether one is right for you.
Russell Ward is an experienced technical writer and structured technologies developer. He has spent many years working with structured content to maximize efficiency in the techcomm environment, both as an employee and as an independent consultant. He is also an experienced trainer and speaks periodically at conferences and other peer events.
Easy steps to convert your content to structured (frame maker and xml)Publishing Smarter
Bernard Aschwanden of Publishing Smarter converts documents that contain character, paragraph, and table content marked up with tags, as well as other standard FrameMaker content and creates structured files. This presentation guides you through the general best practices when converting any legacy content. Forget copy and paste. Leverage what you have to create great structured content. Watch, learn, then do it yourself with provided sample files.
Lotusphere 2007 AD507 Leveraging the Power of Object Oriented Programming in ...Bill Buchan
Co-presented with Jens Augustini
Object Oriented Programming (OOP) may drastically reduce your coding time in projects that reach a higher degree of complexity, as it brings re-usable and consistent logic in the form of your own objects to your fingertips. This session will show how to create and use your own classes and how they can relate to the LotusScript Object Model. If you are familiar with LotusScript but don't know how to create your own classes, this session is for you!
Dita for the web: Make Adaptive Content Simple for Writers and DeveloperDon Day
Lavacon 2013, Portland, Oregon
On the challenges of implementing structured, in-browser editing environements for creating adaptive content for the Web.
Exploiting Layout and Content
Don Day, Contelligence Group
Content creation, reuse, and publishing to everyone on every device (WritersUA)Publishing Smarter
Timing is everything. It's crucial to quickly create content for multiple audiences, manage reuse effectively, and publish to an audience that needs: the right information, at the right time, in the right format. You can follow up and in a hands-on way you: create content for multiple audiences, in seconds generate dynamic HTML5 content, do so at the click of a button
Text-rich, illustration-heavy, table-filled, overly-hyphenated manuals and docs sit on the shelf and never get read.
Today, we read information in the format we want, on whatever device we want, and with just enough information to support what we need to do.
Learn more about topic-based writing, what it is and what it can do for your approach to documentation.
Any device, any time, any format.
Painless XML Authoring?: How DITA Simplifies XMLScott Abel
Presented at DocTrain East 2007 by Bob Doyle, DITA Users -- This introduction to XML Authoring will acquaint you with over fifty tools aimed at structuring content with DITA. They are not just DITA-compliant authoring tools (editors) for writers. They also include content management systems (CMS), translation management systems (TMS), and dynamic publishing engines that fully support DITA. You will also need to know about tools that convert legacy documents to DITA and help to design stylesheets for DITA deliverables. The best DITA tools for technical communicators implement the DITA standard while hiding all the complexity of the underlying XML (eXtensible Markup Language).
As a tech writer and not a tech, you should be able to forget about XML - except to know that you are using it (DITA is XML) and that it consists of named content elements (or components) with attributes. You need to know enough about the content elements so you can reference (conref) them for reuse. You need to know about their attributes so you can filter on them for conditional processing. And you should appreciate that because components are uniquely identifiable they lend themselves perfectly to automated dynamic assembly using a publishing engine.
We will describe how you can get started with structured writing without knowing XML or installing anything.
The promise of topic-based structured authoring is not simply better documentation. It is the creation of mission-critical information for your organization, written with a deep understanding of your most important audiences, that can be repurposed to multiple delivery channels and localized for multilingual global markets. You are not just writing content, you are preparing the information deliverables that enhance the value of your organization in all its markets.
To do that well, you must understand the latest tools in structured writing that are revolutionizing corporate information systems - today in documentation but tomorrow throughout the enterprise, from external marketing to internal human resources. Whether you are trying to push a new product into a new market or are “onboarding” a new employee, the need for high quality information to educate the customer or train the new salesperson is a challenge for technical communicators. You need to think outside the docs!
The key idea behind Darwin Information Typing Architecture is to create content in small chunks or modules called topics. A topic is the right size when it can stand alone as meaningful information. Topics are then assembled into documents using DITA maps, which are hierarchical lists of pointers or links to topics. The pointers are called “topicrefs” (for topic references).
Think of documents as assembled from single-source component parts. Assembly can be conditional, dependent on properties or metadata “tags” you attach to a topic. For example, the “audience” property might be “beginner” or “advanced.”
At a still finer level of granularity, individual elements of a topic can also be assigned property tags for conditional assembly. More importantly, a topic element can be assigned a unique ID that makes it a content component reusable in other topics.
As you will learn, DITA is a leading technology for “component content management,” which multiplies the value of your work. You need to leverage DITA and structured content to multiply your income.
Gone through articles and presentations on the web and got a half-baked understanding of the Darwin Information Typing Architecture (DITA)?
Refer to my DITA Quick Start presentation for the 2007 STC India Conference to learn to evaluate, plan and start implementing DITA.
In this presentation, you will learn about the following:
o Structured authoring and XML
o Key DITA concepts: topics, maps, specialization
o DITA architecture and content model
o Authoring in topics
o Organizing content using DITA maps
o Creating relationship tables
o Conditional text and reuse in DITA
o Metadata support in DITA
o DITA tools, standards and processes
o Publishing with the DITA Open Toolkit
By now, you have heard how important structured content is. But, maybe you poked around with something like DITA and were baffled by the complexity. Or, maybe you still aren’t sure what XSLT stands for. This workshop will take participants back to the basics, to provide a foundation for higher-level concepts that have taken hold of our industry. Topics will include:
- What XML looks like, what it does, and how to create it.
- How to define a structure model, including whether to use a - DTD, Schema, etc.
- What XSLT looks like, what it does, and how to make it work.
- What DITA and DocBook really are and whether one is right for you.
Russell Ward is an experienced technical writer and structured technologies developer. He has spent many years working with structured content to maximize efficiency in the techcomm environment, both as an employee and as an independent consultant. He is also an experienced trainer and speaks periodically at conferences and other peer events.
Easy steps to convert your content to structured (frame maker and xml)Publishing Smarter
Bernard Aschwanden of Publishing Smarter converts documents that contain character, paragraph, and table content marked up with tags, as well as other standard FrameMaker content and creates structured files. This presentation guides you through the general best practices when converting any legacy content. Forget copy and paste. Leverage what you have to create great structured content. Watch, learn, then do it yourself with provided sample files.
Lotusphere 2007 AD507 Leveraging the Power of Object Oriented Programming in ...Bill Buchan
Co-presented with Jens Augustini
Object Oriented Programming (OOP) may drastically reduce your coding time in projects that reach a higher degree of complexity, as it brings re-usable and consistent logic in the form of your own objects to your fingertips. This session will show how to create and use your own classes and how they can relate to the LotusScript Object Model. If you are familiar with LotusScript but don't know how to create your own classes, this session is for you!
Dita for the web: Make Adaptive Content Simple for Writers and DeveloperDon Day
Lavacon 2013, Portland, Oregon
On the challenges of implementing structured, in-browser editing environements for creating adaptive content for the Web.
Exploiting Layout and Content
Don Day, Contelligence Group
Rocky Mountain STC: Best practices when creating interactive video tutorialsPublishing Smarter
Delivered at the Rocky Mountain Chapter of STC, this session explores how to:
*. Develop a storyboard
*. Review a support topic
*. Create a related video
*. Help users visualize how to perform the task
Automating DITA Publishing: How Gulfstream Publishes Style-rich, Interactive ...Publishing Smarter
If you have watched a TV show or movie in which characters travel the world in a Gulfstream, you have seen a company that elevates aviation to an art form. Sleek lines, luxurious cabins, and an ongoing pursuit of excellence are what we see onscreen.
Behind the scenes, there is DITA. Flight manuals, operators manuals, handbooks, and other content is sourced from one set of DITA materials. Gulfstream then publishes it in a system to PDF that is as functional, professional, and sharp looking as the airplanes they support.
How Gulfstream is doing this, though, is another story. It includes highs and lows of discovery, challenge, and success from open communications between partners. The experience of delivering the best looking and the best functioning documentation in the industry means months of effort to create a push-button approach to convert a DITA map to a finished digital PDF that provides a complete solution to online documentation for the cockpit.
This story is a continuing exploration of the boundaries of automation, compliance, design, and a desire to enhance the usability (and the re-usability) of content from creation to the final delivery. See how it works and what DITA can do to change the way we fly.
Convince Management to Invest in a CCMS (Lessons learned)Publishing Smarter
You are keenly aware of the benefits of a Component Content Management System (CCMS). Next steps; develop a business case to present to management. Answering their questions about an important investment decision means prepping for their key questions. This webinar presents you with questions management may ask, information on researching answers, and guidance on how to make your case. Learn through stories of companies and people who have a CCMS. Hear what they did to convince their management teams to make the long term investments that pay dividends for years to come.
Develop key components of a content strategy
Connect the implementation of the strategy with
Improved workflows for creating, managing, and publishing content
Reduction of risk in lack of compliance, inconsistency, missing information
Generation of revenue through effective multi-channel content delivery
Ask (and answer) questions related to tool selection
Hands-on with FrameMaker and DITA to create topics
Publish PDF and HTML5 formats
Implement an Adobe Experience Manager-based solution to ingest, manage, and publish content
DITA: From “Do I?” to “Done It!”: An Automotive Case Study that can apply to ...Publishing Smarter
This session showcases how documentation for one of the biggest auto manufacturers in the world was to migrated to DITA allowing for publishing of hundreds of manuals in over a dozen languages.
Vehicle documentation (owner’s manuals, user guides, quick reference guides, etc) are as crucial to a car as the brakes, engine, or chassis. Without these a car is not finished, and cannot be shipped and sold. Documentation failure can cost over $100,000 per MINUTE if it results in a line being shut down.
Learn about the journey and discovery of concerns, project scope definition and change, trials and tribulations of getting tools to do what was needed, and the net results. Along the way a component content management system, author tools, review processes, and much more had to be planned, tested, implemented, and supported.
Darwin Information Typing Architecture (DITA) is the accepted industry standard for creating structured content. A Unified Content Strategy is the methodical and purposeful management of your information assets across all divisions of your enterprise, in a way that breaks down silos and makes information easy to find and use.
Brakes, engine, or chassis is mission-critical for a car. Equally important is all the documentation (owner’s manuals, user guides, quick reference guides, etc). Without these, a car is not finished, and cannot be shipped or sold. When supporting one of the biggest auto manufacturers in the world meant migrating to DITA, a solution that supported publishing had to work right. It had to work the first time, and every time.
Learn about the journey and discovery of concerns, project scope definition and change, trials and tribulations of getting tools to do what was needed, and the net results. Along the way, a component content management system, authoring tools, review processes, and much more had to be planned, tested, implemented, and supported.
Takeaways:
• Attendees should be able to clearly see what worked, what didn’t, learn why, and avoid similar pitfalls in their path to structured content.
• Identify how a tight time frame, expectations vs reality, last minute changes, and many late nights culminated into results that showcase the best and worst of tech comm and related tools and processes.
• Discover an automated publishing solution, where one source of content is transformed to multiple channels and uploaded to a CCMS.
Make the move from basic documents to structured documentsPublishing Smarter
Word is great when you have content that is managed by SharePoint, or based on standard and highly-enforced templates, or you have a team of developers to support your team of writers. However, there are too many ways for too many people to cause too many problems. Style overrides, manual formats, or just incorrect use of a template can haunt good content. You spend time and effort to make content great; now put a little bit more time into getting to know a tool that isn’t created for everyone. It’s created for those of us who work in technical communication. It’s time for Adobe FrameMaker.
In this session, you will learn how to
» Evaluate a Word document for content quality
» Rework content for a topic-based model
» Import a Word file to Adobe FrameMaker
» Create a structured workflow
» Migrate legacy content to a structured format
» Move your content to a CCMS
» Publish single sourced content to multiple channels, formats & devices
Give in to the power of the Dark Side: Tech Comm and Marketing are ConvergingPublishing Smarter
Video: https://youtu.be/AXPG_d-XiZk
We’ve come to think of it like this: content is content. Marketing and technical communications are generated for the same end users at different points in the product adoption life-cycle. The distinction between marketing communications and technical communications is far less pronounced than it once was. Managers sometimes see little difference in skill-sets and often put content creators together in one role or department – and maybe they’re right. During our careers we’re often dealing with a lot of technical content but also creating marketing communications; we’re in a good position to see how very little difference there might be between them. They’re both an always-on dialogue with the user, just at different points in the product adoption life-cycle. We’ll explore the audiences who consume content, ideas related to a seamless content experience, how both training and support factor into this, and talk about implementation ideas.
Make It All About Your Audience (Deliver What They Want, How They Want, When ...Publishing Smarter
It’s all about the audience and we hear that all the time. Know your audience. Articles and discussions abound about the informed consumer, audience metrics, and personas. How do you actually organize and create content geared to multiple audiences?
Learn tips and techniques for planning, writing, and publishing which help you deliver the right information, to the right audience, in the right format, at the right time, and let them make the right decisions.
DITA can help both marketing and technical communications teams connect with customers. In a non-technical way, this slide deck (and the associated presentation) shows how and why it matters to connect with your customer using all the tools at your command.
Information on business models in Canada, and some background on considerations when starting a business in Alberta. Focus is on general ideas, but details about one tech comm business addressed specifically in the session.
When creating technical documentation it's good to know how long it will take. This presentation (delivered to the STC in Calgary Alberta) explores estimating such projects as well as an overview of the estimating process.
Metrics that matter Making the business case that documentation has valuePublishing Smarter
Tell the story around content as a business asset. We agree there is value in documentation but have been challenged at times to “prove it”. Present to groups including sales, support, service, IT, engineering, QA/testing, manufacturing, HR, training, finance, marketing, and every other business unit in your organization. Demonstrate how documentation drives sales and generates corporate revenue to managers and executives helping them see how important documentation is to them
Metrics that matter: Making the business case that documentation has valuePublishing Smarter
Presented at STC16 Summit in Anaheim, follow a case study in which a product launch was positively impacted by good planning around documentation early in the project.
Content creation, reuse, and publishing to everyone on every devicePublishing Smarter
Use Adobe FrameMaker and its conditional text settings to create content unique to your audience and allow them to choose exactly what they read. Step-by-step instructions make it easy to get started, and explore powerful ideas.
Metrics that matter: Making the business case that documentation has value (r...Publishing Smarter
Tell the story around content as a business asset. We agree there is value in documentation but have been challenged at times to “prove it”. Present to groups including sales, support, service, IT, engineering, QA/testing, manufacturing, HR, training, finance, marketing, and every other business unit in your organization. Demonstrate how documentation drives sales and generates corporate revenue to managers and executives helping them see how important documentation is to them.
Biological screening of herbal drugs: Introduction and Need for
Phyto-Pharmacological Screening, New Strategies for evaluating
Natural Products, In vitro evaluation techniques for Antioxidants, Antimicrobial and Anticancer drugs. In vivo evaluation techniques
for Anti-inflammatory, Antiulcer, Anticancer, Wound healing, Antidiabetic, Hepatoprotective, Cardio protective, Diuretics and
Antifertility, Toxicity studies as per OECD guidelines
Unit 8 - Information and Communication Technology (Paper I).pdfThiyagu K
This slides describes the basic concepts of ICT, basics of Email, Emerging Technology and Digital Initiatives in Education. This presentations aligns with the UGC Paper I syllabus.
Delivering Micro-Credentials in Technical and Vocational Education and TrainingAG2 Design
Explore how micro-credentials are transforming Technical and Vocational Education and Training (TVET) with this comprehensive slide deck. Discover what micro-credentials are, their importance in TVET, the advantages they offer, and the insights from industry experts. Additionally, learn about the top software applications available for creating and managing micro-credentials. This presentation also includes valuable resources and a discussion on the future of these specialised certifications.
For more detailed information on delivering micro-credentials in TVET, visit this https://tvettrainer.com/delivering-micro-credentials-in-tvet/
Read| The latest issue of The Challenger is here! We are thrilled to announce that our school paper has qualified for the NATIONAL SCHOOLS PRESS CONFERENCE (NSPC) 2024. Thank you for your unwavering support and trust. Dive into the stories that made us stand out!
Exploiting Artificial Intelligence for Empowering Researchers and Faculty, In...Dr. Vinod Kumar Kanvaria
Exploiting Artificial Intelligence for Empowering Researchers and Faculty,
International FDP on Fundamentals of Research in Social Sciences
at Integral University, Lucknow, 06.06.2024
By Dr. Vinod Kumar Kanvaria
A Strategic Approach: GenAI in EducationPeter Windle
Artificial Intelligence (AI) technologies such as Generative AI, Image Generators and Large Language Models have had a dramatic impact on teaching, learning and assessment over the past 18 months. The most immediate threat AI posed was to Academic Integrity with Higher Education Institutes (HEIs) focusing their efforts on combating the use of GenAI in assessment. Guidelines were developed for staff and students, policies put in place too. Innovative educators have forged paths in the use of Generative AI for teaching, learning and assessments leading to pockets of transformation springing up across HEIs, often with little or no top-down guidance, support or direction.
This Gasta posits a strategic approach to integrating AI into HEIs to prepare staff, students and the curriculum for an evolving world and workplace. We will highlight the advantages of working with these technologies beyond the realm of teaching, learning and assessment by considering prompt engineering skills, industry impact, curriculum changes, and the need for staff upskilling. In contrast, not engaging strategically with Generative AI poses risks, including falling behind peers, missed opportunities and failing to ensure our graduates remain employable. The rapid evolution of AI technologies necessitates a proactive and strategic approach if we are to remain relevant.
2024.06.01 Introducing a competency framework for languag learning materials ...Sandy Millin
http://sandymillin.wordpress.com/iateflwebinar2024
Published classroom materials form the basis of syllabuses, drive teacher professional development, and have a potentially huge influence on learners, teachers and education systems. All teachers also create their own materials, whether a few sentences on a blackboard, a highly-structured fully-realised online course, or anything in between. Despite this, the knowledge and skills needed to create effective language learning materials are rarely part of teacher training, and are mostly learnt by trial and error.
Knowledge and skills frameworks, generally called competency frameworks, for ELT teachers, trainers and managers have existed for a few years now. However, until I created one for my MA dissertation, there wasn’t one drawing together what we need to know and do to be able to effectively produce language learning materials.
This webinar will introduce you to my framework, highlighting the key competencies I identified from my research. It will also show how anybody involved in language teaching (any language, not just English!), teacher training, managing schools or developing language learning materials can benefit from using the framework.
2. Overall Objectives
13:51@publishsmarter
2
Advantages to authoring in a topic based environment
More efficient
Structure helps produce better content
Takes advantage of new technologies for delivering content
I plan to share the best way to
Assess your current situation
Plan for your future and
Execute to the plan
After the presentation, you will:
Understand what topic–based writing is and its advantages
Follow best–practices for organizing new material into topic–based
content
Understand the place of XML and DITA and how they may relate to
your needs
3. Housekeeping and note taking
13:51@publishsmarter
3
Not all slides or topics are
equally weighted
Use some, discard others
Slides speed varies
(reference)
Questions? Ask along the
way!
I’d love to claim errors/typos
is on purpose… they isn’t,
ain’t, and weren’t never;
however, I’ll fix ‘em as I
can…
4. About your speaker
13:51@publishsmarter
4
Publishing Smarter:
President
Content strategist,
publishing technologies
expert, author, and geek-
enough
Certified Technical Trainer
DITA
Content management
Topic-based writing
Society for Technical
Communication
Vice President
STC Associate Fellow
5. Standard disclaimer
13:51@publishsmarter
5
In the interest of brevity I
will make some blanket
statements to keep it
simple
It’s not all 100% “the
truth”, but I’ll stay close
Purists may complain
And they are wrong!
(except when they are
right)
7. Topic-based single sourcing is more efficient
13:51@publishsmarter
7
Use the same content in more than one location
This could be across:
Output types (online help, user’s guide)
Perhaps graphics are excluded, or specific topics not
needed/added
Projects (new version re-uses content from last version)
Products (t40 and t41 are similar products, 90% the same)
Departments (Marketing re-uses Doc’s content)
User types (novice and advanced users)
Operating systems (Windows, Mac, Unix, Android)
Many instances of the same topics, unique order
8. If you single source
13:51@publishsmarter
8
Try to share topics in their entirety
Create content that is free of ‘specifics’
Product names
Screen shots
Other identifying content
If you need specifics, can you conditionalize ‘chunks’
Entire sections
Paragraphs
Images
10. Defining topic-based writing
13:51@publishsmarter
10
A way to create content from standalone topics
which are:
Smallest possible unit of information that makes sense on its
own (no absolute dependencies)
Reusable as a standalone unit of information
Based on information type (e.g., concept, reference, task)
Can be assembled to create help, HTML, PDF, etc
Linked and referenced to build relationships
Not applicable to all doc types though
Marketing, legal, regulatory may be far more focused
However, ideas can still apply (targeted writing)
11. Reasons topic-based is a good idea
13:51@publishsmarter
11
An alternative to linear writing
Traditional book model
Writing in chapters
Order matters (before/after)
A method of focusing on your users’ needs
A way to chunk information based on types
Fundamentally, a way of organizing your content into
easily digestible pieces
12. The linear approach to content
13:51@publishsmarter
Linear means:
Content is related to
previous and following
content
It's not easy to re-order
If you do NOT know the
order, then the context
can be lost very quickly
12
13. The modular (topic-based) approach to
content
13:51@publishsmarter
Modular means:
Pieces of information
must make sense without
context
Pieces of information can
be moved around
Context may or may not
bring extra meaning to
individual pieces
People jump in where
and when they need
content
13
14. Benefits to writers and users
13:51@publishsmarter
To the writer
Team collaboration
Easier review cycle
Create it faster
Solid time management
Less time formatting
Share content
Shorter content
Fewer opportunities for
mistakes
To the user
Read what you want
Read in the order you
want
Common layout makes it
fast to scan and find
content (beyond search)
14
15. It makes content better
@publishsmarter 13:51
15
Structure (and XML)
16. XML supports structured writing
13:51@publishsmarter
16
Structure implies a set
of defined rules (law,
math, engineering,
grammar)
Writing implies the
creation of content
Structured content
consistently follows rules
A good foundation
results in a happy home
17. What does it look like?
13:51@publishsmarter
17
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
18. What does it look like?
13:51@publishsmarter
18
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
19. What does it look like?
13:51@publishsmarter
19
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
20. What does it look like?
13:51@publishsmarter
20
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
21. Human usable XML might look more like this
13:51@publishsmarter
21
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser“>
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
22. Reading it can be pretty simple (ignore code)
13:51@publishsmarter
22
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser">
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
23. Structure has some human-friendly feel to it
13:51@publishsmarter
23
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser">
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
24. You can even understand the attributes
13:51@publishsmarter
24
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser">
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
25. Remember that XML provides a division
13:51@publishsmarter
25
Format
Content
26. With XML you spend your time wisely
13:51@publishsmarter
26
27. There ARE better ways to write,
so take advantage of them!
@publishsmarter 13:51
27
New technologies
28. Notepad. You can edit with Notepad. Woo.
Hoo.
13:51@publishsmarter
28
29. Code view if you want/need it
13:51@publishsmarter
29
30. Code view is only one option
13:51@publishsmarter
30
38. Net benefit of two topics, one source
13:51@publishsmarter
38
Less editing
Fewer edits
Less review time
Quicker approvals
Fewer overall words to manage
And, as the content is created, you can publish to
any output that you need!
39. It is not output restrictive
13:51@publishsmarter
42. High level ideas on the day-to-day
writing of content
@publishsmarter 13:51
42
How to think about DITA
43. DITA in a single slide
13:51@publishsmarter
43
D is for Darwin
Evolves and adapts, over time DITA is adding
new topic types, elements, as well as tools
and best practices
Specializes, when it can’t meet your needs,
you can customize
IT is for Information Typing
Info is organized/classified into
task/concept/reference
A is for Architecture
A formal set of rules
Planned and developed
DITA is primarily about
Topics and Maps (and planning)
Connect People
and Content
44. Identify topic types
13:51@publishsmarter
44
topic: A meaningful, stand–alone unit of
information, eg. Work with images
three primary topic types matter
task: Procedural details such as step-by-step
instructions. eg. Import images, Resize images
concept: Background info that users need to
know. eg. Reasons to use images
reference: Quick access to tech info, or facts.
eg. Supported image formats, Raster versus
vector
map: Contains info about relationships
between topics, appropriate metadata,
and optional linking and navigation
TOPIC
REFERENCECONCEPT
TASK
45. DITA begins with thinking of tasks
13:51@publishsmarter
45
The task identifies the
best practice to follow
to achieve a goal
Step-by-step
Minimal other
information
46. If needed, concepts support tasks
13:51@publishsmarter
46
The concept
introduces the ideas
Answers the
questions of “what is”
or “why would I” that
people have
47. For technical info, references help
13:51@publishsmarter
47
Quick access to facts
Usually a lookup for
people who know the
concept, understand
the task, but need the
quick technical specs
49. When topics and maps come together
13:51@publishsmarter
A resulting hierarchy of
information exists
Materials are easier to
read, quicker to scan
When published, delivers
minimalist, clear, and
easy to use content
The result of using DITA
is more than just clear
content
Navigation between
topics automatic
Further navigation can
also be developed
49
TOPIC
REFERENCECONCEPTTASK
50. Best practices
While they are BEST practices,
there is a formal approach to them in DITA
@publishsmarter 13:51
50
Things you can do to start
51. Quick steps to ID what you actually have
13:51@publishsmarter
51
Review your table of contents
Build a TOC with steps, figures, tables in it
Review it again
Start to quickly ID
See if you can guess what is a task/concept/reference
Compare your TOC info with the body of the content
If there isn’t a match that is a clear T, C, R, then rework (ideas
follow)
52. Tasks are core in DITA
13:51@publishsmarter
52
Remember that tasks are a core part of DITA
Odds are people are doing things when they
discover a need to look up docs
Tasks are the most likely place users turn
Make sure you explain the “how to” and support that
with other information
53. Best practices (both DITA and minimalism)
13:51@publishsmarter
53
Stick to one way to tell people how to do it
Don’t mix icons, shortcuts, and menus in a task (I like Select
File > Open. Menus rarely are customized/hidden unlike
keyboard commands or toolbars) BTW: Good design is also
good minimalism!
Avoid features (that’s concept)
<cmd> is 1 sentence
If needed, 1 level of substeps
Avoid stem sentence lead-ins
Best: Clear title, familiar patterns
Less to translate and manage
54. Rework a source quickly
13:51@publishsmarter
54
Take the next slide and mark it up
Use (color, bold, italic, whatever…) to ID topic type
Task, concept, or reference identifiers
Rework into core task/concept/reference
This is an online exercise, and I’ll use the chat, but
you can do this on your own with your content too!
Later: Find a good sample of your own content,
and try this for yourself
55. 13:51@publishsmarter
55
Microsoft Word, Excel, and PowerPoint allow you to
insert a graphic. Graphical images add value to
documents by making it easier to see any type of
idea represented as a picture. They also break up
content rich materials. Many formats (including
common ones like jpg, gif, bmp, or even pdf) are
supported in most of the tools. To insert an image in
any one of these applications you can use the Insert
menu and choose Picture after you select a
location. Then choose and import an image in one
of the supported formats. Make sure you manage
graphics well! You may want one folder for all your
images instead of looking everywhere for them.
56. 13:51@publishsmarter
56Microsoft Word, Excel, and PowerPoint allow you to
insert a graphic. Graphical images add value to
documents by making it easier to see any type of idea
represented as a picture. They also break up content rich
materials. Many formats (including common ones like
jpg, gif, bmp, or even pdf) are supported in most of the
tools. To insert an image in any one of these
applications you can use the Insert menu and
choose Picture after you select a location. Then
choose and import an image in one of the supported
formats. Make sure you manage graphics well! You may
want one folder for all your images instead of looking
everywhere for them.
Task Concept Reference Undecided
57. 13:51@publishsmarter
57Microsoft Word, Excel, and PowerPoint allow you to
insert a graphic.
Task: To insert an image in any one of these
applications you can use the Insert menu and
choose Picture after you select a location. Then
choose and import an image in one of the supported
formats.
Concept: Graphical images add value to documents by
making it easier to see any type of idea represented as a
picture. They also break up content rich materials. Make
sure you manage graphics well! You may want one
folder for all your images instead of looking everywhere
for them.
Reference: Many formats (including common ones like
jpg, gif, bmp, or even pdf) are supported in most of the
tools.
58. Add linked pictures (Task)
13:51@publishsmarter
58
Linked graphics ensure that when a
source changes, your documents remain
current.
Prerequisite: Use specific tools to create
images first; then add images as needed.
1. Choose a location for an image
2. Select Insert > Picture
3. Choose an image type
4. Double click the image to import
When done: Position or size the image.
59. Reasons to use graphics (Concept)
13:51@publishsmarter
59
Graphics add value to documents by
making it easier to see ideas
represented visually. They also break up
text rich materials.
TIP: Manage graphics well! You may
want one image folder with all images
instead of looking everywhere for them.
60. Supported formats (Reference)
13:51@publishsmarter
60
Multiple image formats can be imported.
Type Value Description
Raster image:
Joint
Photographic
Experts Group
jpg or
jpeg
Often used online,
good for photos or
gradient based
images, high color
definition support
Raster image:
Graphics
Interchange
Format
gif Often used online,
good for basic image,
up to 256 color
support, includes
transparency
61. Work with graphics (Topic)
13:51@publishsmarter
61
Microsoft Word, Excel, and PowerPoint
allow you to insert a graphic.
62. Pulling those topics into a map and
publishing to multiple outputs...
@publishsmarter 13:51
62
Bring it home...
66. In FrameMaker
13:51@publishsmarter
66
DITA > New DITA File > New <task> and View >
Element Boundaries as Tags, the populate task (if
desired, also show Element > Catalog and Structure
Tools > Structure View
Tutorials: www.publishingsmarter.com
68. If you build a map, you can also publish it all
13:51@publishsmarter
68
69. Summing up the discussion,
and options to continue it.
@publishsmarter 13:51
69
Conclusion and contact
70. Overall Objectives
13:51@publishsmarter
70
Advantages to authoring in a topic based environment
More efficient
Structure helps produce better content
Takes advantage of new technologies for delivering content
I plan to share the best way to
Assess your current situation
Plan for your future and
Execute to the plan
After the presentation, you will:
Understand what topic–based writing is and its advantages
Follow best–practices for organizing new material into topic–based
content
Understand the place of XML and DITA and how they may relate to
your needs
71. Follow up contact information
13:51@publishsmarter
71
905 833 8448 (Eastern Time)
bernard@publishingsmarter.com
www.linkedin.com/in/bernardaschwanden
@publishsmarter
www.publishingsmarter.com