Nolwenn Kerzreho, IXIASOFT
June 1, 2020
Some writers and specialists claim it’s too difficult to write in DITA and that the learning curve is too steep. Some other specialists and documentation managers claim that they can start new hires writing in DITA in a couple of hours.
This article is the follow-up of a series of articles about writing practices that authors must adapt, adopt, or shed.
We will focus here on the new practices that authors must adopt when writing using DITA. Of course, the trajectory and requirements for each company are different. Still, the most important hurdles for authors usually relate to these three aspects: accessibility, navigation alternatives, and writing for reuse.
Writing for new audiences and delivery channels
Most writers need to adopt new practices as they must let go of the idea that they own the delivery format and can know in advance what final media will be used for the information they craft. In most cases, difficulties arise from delivering to web channels, including websites, mobile sites, phone applications, or even onboard media centers.
Accessibility — an opportunity for all
New media outputs create new demands on the content crafted but also new opportunities. Accessibility is a major factor that can enhance the content experience for all users, and not only those with disabilities. Accessibility on web and digital formats are of the utmost importance. It may be even mandatory if you are working in a field for broader audiences and public services.
The main guidelines for the Web Accessibility Initiative (WAI) are led and hosted by Web Content Accessibility Guidelines Working Group from the W3 consortium. The impact on content for DITA authors lies mostly in tagging so that the publishing tool can understand and process your content effectively. As a result, screen readers (and other assistive technology tools) can parse the information in an effective way.
Note that the 2.1 version of the guidelines includes new advice for assistant tools and inputs for user experience with motions, rotations, and so on.
Accessibility for images, figures, and tables
The baseline is to use descriptions of images to convey the meaning of these images, graphs, etc. As a rule of thumb, if there is nothing to say about an illustration, it is a good indication that the image itself may be removed safely from the content. Images that are void of meaning are not only redundant; they burden the reader. In the end, they will not even be looked at by users.
The figure element should encapsulate:
- Title
- A pointer to an image
- An alternative text – web accessibility rules
- A descriptive text – web accessibility rules
Alternative text is the explanatory text for screen-readers. Visually impaired customers will hear a description of the image. Again, if there is no description needed for an image, maybe the image can go away.
Writers should use the proper lists tags and not commas to list items.
For table elements accessibility, writers should:
- Add a descriptive text
- Specify which line header or column header makes sense1
These are the main points each author should adopt for writing DITA content. I strongly recommend every writer to check out the WAI guidelines that are available online for free. You will find that the transformation process complies with the basic rules for web accessibility, including heading levels and tagging, link tagging, and so on, but still provides good insights and reminders.
Alternative navigations
Considering that a narrative path does not apply to most technical information sets, authors adopting DITA can add alternative navigation in addition to a table of content and indexing. The goal is to link related information so that readers can click on links to navigate directly to other parts of the information set. For example, to add a link between a maintenance task and a schedule, or to add a logical sequence for a set of tasks.
But where to place these links? Adding links inside the topic’s body can lead your readers to step outside of the current topic before they finished using it. This poses a threat as they may not come back to complete a procedure or read the entire conceptual information. We already know that best practices on the web recommend adding additional links at the end of topics. DITA offers a better way to automatically create the links at a higher level (in the map), thus removing them entirely from the topics themselves.
Removing these dependencies between topics will remove the need to final check what topics are nested in a document.
Authors should never assume the reading order, and this is also true with topic-based authoring. Avoid adding phrases relating to external information such as heretofore, hereafter, as you’ll see in the next topic, etc.
Reusing content
One of the main reasons to adopt modular content is the ability for authors to reuse instead of rewrite or copy and paste content.
The best practices2 to adopt are to identify and separate the content for publishing and the content for reuse. Then to reuse wisely. The old joke is that the maximum reuse level is one letter. Still, these reuse methods are listed from the easiest to the hardest:
- Reusing maps (document) or an entire group of topics
- Reusing independent topics
- Blocks, text segments, images
- Letters (!)
The standard allows you to select different ways of reusing content. You can use various mechanism, such as:
- Reuse with direct hypertext linking
- Reuse with content reference
- Reuse with indirect reference, through keys
Keys are becoming more and more widely used; however, the combination of key and conref is possible and powerful.
Additional advice
The final advice and practice for authors would be to a) test and b) document the architecture choices that are made within the organization. An Information Architect would usually help craft the content model, or information design, for your team. If you do not have an internal resource, it is essential that you hire someone with the appropriate level of understanding and experience to help your team.
The validated choices should then be added to your current style guide. You may also want to create templates to help authors. There are editing tools available to integrate your style guide rules directly in your editor.
Note that Comtech Services has contributed a sample style guide that can serve as a starting point for your own style guide3.
——————————————————————————————————————————-