Course overview

End-user Writing project Advanced Interview

Basics Process Concepts Tools Wrap up
documentation management topics preparation

Day 1 Day 3 Day 6 Day 8 Day 13 Day 15 Day 18 Day 19 Day 20

Day 2 Day 4 Day 7 Day 9 Day 14 Day 16

Day 5 Day 10 Day 17

Day 11

Day 12
Day 18
Advanced topics
Day 18: Advanced topics
 DITA Primer
 Cloud Documentation
 Mobile Documentation
DITA
What is DITA
 Darwin Information Typing Architecture
 Developed by IBM now an OASIS (Organization for the
Advancement of Structured Information Standards) standard
 XML-based Darwin Information Typing Architecture (DITA) as an
end-to-end architecture for creating and delivering modular
technical information.
Difference between HTML and XML
 HTML defines how content is formatted in a web browser; XML
defines what the content is.
 HTML provides a set of predefined tags; XML provides a syntax
that allows users to define their own tags.

HTML example XML example

<ul> <family>
<li>Apple</li> <father><name>Jim</name></father>
<li>Banana</li> <mother><name>Mary></name></mother>
<li> Mango</li> </family>
</ul>
Extend XML tagging
 XML tagging can be extended as data access requirements
change, for example you can add a “surname” element to identify
the last name for sorting purposes
 Attributes provide information about your data:
 Adding an attribute called “gender” to the “child” element allows you to
distinguish boys from girls
 Examples of possible attribute applications for content: Product Name,
Product Version, etc.
Benefits of XML
 XML is a text format that follows an open standard
 Is not bound to proprietary authoring tools or formats
 Is platform-independent, enabling easy information exchange
 Enables information reuse at the sub-document level
 Hierarchical nesting of markup tags creates containers of content within a
document
 Referencing an element includes the information contained within that
element, allowing reuse of information at multiple levels of granularity: an
entire topic, a set of steps or individual step; a glossary entry (term +
definition)
 Separates content from formatting
 Different groups/formats can point to the same piece of content without
reformatting or retagging the information
 Enables dynamic transformation of data
Need for XML standards for tech
docs
 Document-centric XML didn’t grow nearly as fast as data-centric
XML. XML standards bodies focused more on data-centric
standards.
 Home-built DTDs a challenge
 Need for more collaborative authoring within and across
organizations
XML standards for tech docs
 Two “popular” open source standards
 DocBook
 DITA
 Each standard takes fundamentally different approaches
 DocBook
 Best suited for linear content: books and articles.
 DTD covers all possible authoring requirements.
 Does not support truly modular content.
 Incomplete reuse and cross-referencing mechanisms
 Difficult to customize the DocBook DTD. Customization is through hiding
of elements that are not required.
XML standards for tech docs
 DITA XML architecture is based on a Topic DTD and a Map DTD
 DITA information architecture is based on topics ─ units of
information that serve as building blocks for all content
 DITA maps assemble topics for specific documentation
deliverables
Core design principles of DITA
 Topic orientation
 Discrete units of information covering a specific subject with a specific intent
 Topic granularity
 Topics combine with other topics into information sets
 Consistency
 DITA DTDs guarantee that DITA information types follow identical information
structures
 Separation of content (specific topics) from context (links to other
topics, files, navigation)
 Not just separation of content from formatting!!
 Inheritance
 Has a top-level “generic” information type from which other types inherit their
structures
 Specialization
 Ability to extend basic information types for special uses
Information types in DITA

Topic

Concept Task Reference

Why only 3 information types?
 DITA considers that other information types are basically
derivatives of the three core information types: Concept, Task and
Reference.
 If required, you can customize the core information types to
derive other information types using DITA specialization.
 DITA does not claim to cover all requirements. It covers a base
set or requirements and allow other requirements to be covered by
extensions.
Concept topics
 Concept topics introduce the background or overview
information for task or reference topics.
 Concept topics should not describe task or reference
information.
 Concept topics have the restriction that following a section or
example, only other sections or examples are permitted as
content. This ensures that readers are not confused about the
content between sections or examples.
 Chunking rule: In a concept topic, explain only one concept.
Task topics
 Task topics describe the steps of a particular task, or provide an
overview of a higher-level task.
 Task topics should not describe conceptual or reference
information.
 Chunking rule: In a task topic, describe how to do only one
task.
Reference topics
 Reference topics provide quick access to facts. They describe
product features, commands, and so on.
 Information needed for deeper understanding of a reference
topic or to perform related procedures should be provided in a
concept or task topic.
 Reference topics should be designed for quick scanning of
information using lists, tables, and such.
 Reference topics should not describe conceptual or task
information.
 Chunking rule: In a reference topic, explain only one
subject─for example, explain only one command.
Structure example
Concept topic Task topic Reference topic
<concept> <task> <reference>
<title> <title> <title>
<titlealts> <titlealts> <titlealts>
<navtitle><searchtitle> <shortdesc> <shortdesc>
<shortdesc> <prolog> <prolog>
<prolog> <taskbody> <refbody>
<conbody> <prereq> <example> | <section> | <refsyn> |
<section> | <example> <context> <table> |
<related-links> <steps> <simpletable> | <properties>
<result> <related-links>
<example>
<postreq>
<related-links>
Why structure topics by information
type?
 Benefits for Writers
 Standard, consistent structures for authoring content
 Writers can use topic types to more effectively outline information needs
 Helps to analyze information according to the purpose or function it
serves for the reader
 Organizing common types of information with topics help writers spend
more time focused on authoring content
 Choice for selecting the best and most consistent way to present
information, based on information type
 Identify missing information
 Breaking down information into chunks
Why structure topics by information
type?
 Benefits for users/readers
 Standard content structure helps readers to quickly identify a topic’s
purpose
 Readers learn and retain different types of information better when they
are written in a consistent, predictable way
DITA maps
 DITA maps assemble topics into a coherent set for documentation
deliverables.
 Ability to reuse and repurpose the same content for different
deliverable types and for deliverables for different audiences and
products.
 Maps can include DITA topic (.dita) files, XML (.xml), files, HTML files,
PDFs, and more.
 Same topic can be referred to more than once in a map or in different
maps.
 Maps can be nested into other maps to build documentation
deliverables.
 Maps can be combined together manually or using scripts during the
production process.
 DITA map files have the .ditamap extension.
DITA maps
 Separate of content (specific topics) from context (links to other topics, files,
navigation)
 Links are specified in the DITA map and not in the topic file itself. Helps topics remain
“stand alone”.
 Links are automatically generated for the topics from the DITA maps.
 Helps automatically update links if topic title or topic file location changes.
 Build a relationship table to generate “related topics” links
 Goes beyond sequential ordering
 Similar to creating cross references, but moves linking mechanism from content into the
map
 Links are generated only in the output version of the topics
 Increases reusability—no broken links when taking a piece of content out of context
 Sets properties of the topic at a position within the hierarchy
 Properties include the title and metadata
 Can change the topic title relative to the parent topic
 Metadata can identify a topic as advanced for one deliverable and basic for another
 Can provide multiple views on the same topics: by product, by task, by topic
type, audience and so on.
Different deliverables using DITA
maps
Topic 1 Quick start
guide

Topic 2
Reference
guide
Topic 3

Installation
Topic 4 guide
Different formats using DITA maps
Topic DITA maps Delivery formats
1
Compiled help CHM
1 2 4
1 2 4
2 3
Print output HTML
1 4
3
1 3 4

4
Website
2 3 4 PDF
2 3 4
Metadata support
 DITA supports a variety of standard and custom metadata:
 Author information
 Copyright information
 Product information
 Resource IDs for help systems
 Document tracking information
 Audience information
 Keywords
 Custom metadata (otherprops)
 Metadata is supported using the <prolog> element in topics and
<topicmeta> in maps.
Reuse in DITA
 Reuse flows from the topic-based paradigm
 Topics can be reused in different contexts
 Topics from multiple components can be integrated as a solution
 Reuse methods
 Element-level reuse with <conref>
 Topic-level reuse with <topicref>
 Map-level reuse with <navref> and <anchorref>
 Conditional reuse
Reference content
Conrefs are a way to reference content from the same or another DITA file.

Example
 Code in source file source.dita:
<step id="commonstep">
<cmd>This step exists in a common file and is added with a conref.
</cmd>
</step>
 Code in target file B:
<step conref=“source.dita#task/commonstep"><cmd></cmd></step>

Note that the <cmd> tags are included even through they will be replaced by
the conreffed information.
Conditional reuse
 DITA gives you four ways of tagging conditionally using AND/OR
logic:
 Audience
 Platform
 Product
 Otherprops
Example:
The king and queen of Olympus are <ph
audience="greek">Zeus</ph><ph audience="roman">Jupiter</ph> and
<ph audience="greek">Hera</ph><ph audience="roman">Juno</ph>.

When audience=“greek” is set to include, this reads

The king and queen of Olympus are Zeus and Hera.
When audience=“roman” is set to include, this reads
The king and queen of Olympus are Jupiter and Juno.
Inheritance in DITA
 Topics inherit from DITA’s base “Topic” making it possible to extend through
specialization
 Inheritance means that new document structures don’t break publishing tool
chains
Task topic Concept topic Reference topic

Common structure Header: Header: Header:

Title Title Title
Short description Short description Short description
Prolog Prolog Prolog
Body: Body: Body:
taskbody conbody refbody
Related links Related links Related links
Examples of optional Context Section Section
elements (within body) Prerequisites Paragraph Paragraph
Steps Lists Lists
Step-elements Tables Tables
Results Images Images
Examples Examples Examples
Post requirements
Typical DITA workflow
1. Identify the task topics.
2. Identify the concept and reference topics needed to support the
task topics.
3. Create the topics.
4. Use DITA maps to assemble topics for each documentation
deliverable.
5. Publish and deliver the content.
DITA tools
 Modeling tools
 IBM Task Modeler-for creating DITA maps
 Authoring tools
 Authorit
 Arbortext Epic Editor
 XMetal
 Syntext Serna (http://www.syntext.com)
 FrameMaker 8 or above with Adobe FrameMaker 8 Plug-in for DITA Open Toolkit
 DITA Storm (browser-based DITA editor)
 Production tools
 DITA Open Toolkit (http://dita-ot.sourceforge.net/)
 Content management systems
 Astoria CMS, EMC Documentum, PTC Windchill, SiberLogic Sibersafe, Vasont
CMS
DITA resources
 DITA Standard
 OASIS DITA Technical Committee
http://www.oasisopen.org/committees/dita
 DITA Articles
 XML Cover Pages: http://xml.coverpages.org/dita.html
 DITA Users: http://www.ditausers.org/
 http://dita.xml.org
 http://www-128.ibm.com/developerworks/xml/library/x-dita1/
 http://www.slideshare.net/search/slideshow?q=DITA
 Books on DITA
 Introduction to DITA: A User Guide to the Darwin Information Typing
Architecture by Jen Linton and Kylene Bruski, Comtech Services (
http://www.comtech-serv.com/dita.shtml )
DITA resources
 DITA Demos / Webinars
 FrameMaker 8 Deep Dive: DITA Topic-based authoring
https://admin.adobe.acrobat.com/_a227210/p76122134/
 DITA User Groups
 http://groups.yahoo.com/group/dita-users/
 http://groups.yahoo.com/group/framemaker-dita/
 http://dita.xml.org/user-groups
DITA examples
 WebSphere Application Server Documentation: http://www-
306.ibm.com/software/webservers/appserv/was/library/
 Adobe Creative Suite documentation
 Adobe Acrobat documentation
 Apache Derby documentation
 Eclipse documentation
Cloud based
document
management
Cloud document management
systems
 No matter the vertical, any successful organization needs a reliable
way to access critical data securely, quickly and easily, from as many
locations as possible.
 Document management systems – both on-premise and in the cloud
– exist to help accomplish this goal. The best ones streamline
document capture (scanning, digital importation, etc.), document
storage (tagging and indexing), document retrieval (full-text search,
metadata search) and version control (audit trails, check in/out, etc.)
into a single efficient, user-friendly package.
 In on-premise document management systems, data is managed,
stored and processed on servers located within the confines of an
individual business.
 Cloud document management systems do the same on dedicated
servers located in off-site data centers and accessed via encrypted
VPN connections.
Cloud document management
systems
 Leading cloud document management providers, like Cabinet,
house their servers in secure, redundant data centers protected by
biometric scanners, digital firewalls and multiple sources of power
and cooling. This ensures that only authorized users can access
the stored data, and likely provides better security than local
servers, which must be maintained by in-house IT staff or
outsource resources.
Why cloud management
 Cloud document management systems are designed to help
organizations go paperless.
 Frees up valuable office space, decreases or eliminates wasted time
searching for documents, streamlines workflows and more.
 Reduces the burden on IT staff, who can focus on creating
efficiencies and troubleshooting elsewhere.
 Makes collaboration as simple as possible. Multiple offices in
separate locations can access the same documents securely, using a
range of devices.
 Employees who work remotely can get up to speed fast on daily
tasks. This allows organizations to disseminate important information
quickly, confident that everyone is receiving the same trustworthy data.
 When authorized employees can share and collaborate on
documents quickly and easily, efficiencies manifest themselves.
Why cloud management
 Critical content back-ups: Documents, PDFs, emails, images and
more are backed up on redundant storage devices, easing disaster
recovery and all but eliminating the threat of catastrophic data loss.
 Cost effectiveness: Going paperless saves valuable resources, and
using remote, dedicated serves reduces the need for onsite IT services
and equipment.
 Ultimate efficiency: smoother, faster and easier workflows with your
data stored in a cloud document management system.
 Safe and secure: All documents are 100 percent your property. All
transmission to and from the cloud are encrypted through a secure
connection, so only authorized users can access the data.
 Ongoing support: Simply call or email technical support team with
any questions or issues. You get ongoing web-based training, data
backups and automatic software updates mostly at no additional
charge.
Try these cloud based tools
 Office 365: http://office.microsoft.com/en-us/try/
 ClickHelp: http://clickhelp.co/
 Author-it Cloud Enterprise Authoring Platform:
http://www.author-it.com/?page=productaitcloud
 Adobe Creative Cloud: https://creative.adobe.com/
Documenting for
Mobile devices
Go mobile
 With a surge in mobile use, and an increase in distracted users
that are strapped for time, adapting your content to fit into the on-
the-go lifestyle is becoming more and more prevalent.
 Think about what people want to do on the move, and why they
would be using a mobile device. Are they task focused? For
example checking an address, making a booking or finding a
phone number. Are they killing time? For example are they on a
long train journey or waiting for a friend.
 Your content and navigation is of paramount importance in
providing the user with a smooth journey through your site.
Challenges
 Small screens, multiple apps and functions, dual screening, and
a busy on-the-go context of use all conspire to make mobile web
the most challenging platform to write for.
 To get your message across, you need to write in succinct, plain
language.
 Make sure your content is tightly focused on user benefits.
 You have to make image styling responsive on tablet and mobile
devices. Mobile screens are smaller than desktops, and
touchscreen responsiveness can’t always be the most reliable.
 Recording mobile screencasts requires some extra hardware.
Tap
 Adapting your call to action ‘click here’ is important on a mobile
site.
 Your user isn’t clicking a mouse, he or she is tapping a screen so
it’s essential to change links to ‘read more’ or ‘see more of product
A’.
 Making sure that link text is long enough to provide a good-sized
target to tap on can be really helpful.
‘On the go’ information
 Mobile visitors are often looking for 'on the go' information, which
is one of the main things to consider when thinking about your
content.
 Make sure information like 'Where to find us' 'Phone number'
and 'Product reviews' (if you have them) are easy to find on
entering the mobile site.
 Use ‘Progressive disclosure’ to defers advanced or rarely used
features to a secondary screen, making applications easier to
learn and less error-prone.
 Progressive disclosure is one of the most simplest yet powerful
ways to satisfy the content simplicity and richness:
 Initially, show users only a few of the most important options.
 Offer a larger set of specialized options upon request.
 Disclose the secondary features only if a user asks for them, meaning
that most users can proceed with their tasks without worrying about this
added complexity.
Benefits of progressive disclosure
 In a system designed with progressive disclosure, the very fact that
something appears on the initial display tells users that it's important.
 For novice users, this helps prioritize their attention so that they
only spend time on features that are most likely to be useful to them.
 By hiding the advanced settings, progressive disclosure helps novice
users avoid mistakes and saves them the time they would have
spent contemplating features that they don't need.
 For advanced users, the smaller initial display also saves them time
because they avoid having to scan past a large list of features they
rarely use.
 Progressive disclosure thus improves three of usability's 5
components: learnability, efficiency of use, and error rate.
 By initially focusing users' attention on a few core features, they
understand a system better when you help them prioritize features and
spend more time on the most important ones.
 Staged disclosure: one step at a
time
 Staged disclosure is a variant in which users step through a
linear sequence of options, with a subset displayed at each step.
 Wizards are the classic example of staged disclosure.
Progressive Disclosure Staged Disclosure
Initial display Core features Features that users access first in the task sequence
Subsequent display(s) Secondary features Features that users access later in the task, even if
these features are equally important (or more
important)
Do users access Usually not — most users get what Yes — unless users stop the task before completing
subsequent displays? they need on the initial display the sequence
Navigation between Hierarchical: users start at the initial Linear: users progress through the task one step at a
displays display and, if necessary, move to the time
secondary display and then (often)
return to the initial display
Key takeaways
 Overview and architecture of DITA; XML standards in tech
documentation, concepts, tasks and reference- where, how and
when.
 How to document in Cloud, Tools using Cloud, Models, concepts
 Introduction to unique challenges of developing content for
mobile devices, content disclosure techniques.
Course so far

End-user Writing project Advanced Interview

Basics Process Concepts Tools Wrap up
documentation management topics preparation

Day 1 Day 3 Day 6 Day 8 Day 13 Day 15 Day 18 Day 19 Day 20

Day 2 Day 4 Day 7 Day 9 Day 14 Day 16

Day 5 Day 10 Day 17

Day 11

Day 12