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 final part of a series of posts about writing practices that authors must adapt, adopt, or shed.
Letting go of styles
It may seem counter-intuitive, but letting go of specifics from old tools and other proprietary formats is sometimes the most challenging part for authors. When adopting DITA, teams must learn to work with modular and structured content. The latter means that the technical writers are focusing on the content and not on how it looks.
Making sure this list bullet point is just right, the indentation is perfect, changing the title font can eat up 50%, even 80% of the time of content developers. With structured content, a lot of time can be saved by separating the content from the layout and applying automated branding on the different media rather on the content.
The benefits are two-fold:
- More time for the content developers to work on content
- Branding is controlled on stylesheets, independently of the content
Letting go of styles also means that the next time your organization logo changes or when the branding is updated, content teams will only need to update the stylesheets once – not all the relevant documents.
Adapting the authoring experience
We discussed using tags instead of styles in the first article in this series. However, it is worth highlighting that most modern structured editors can provide authoring assistance that will help authors transitioning to DITA.
First, most editor tools provide a preview of the content in their interface, thus providing a good visual indication of where tags are missing and how the content will look like, for example, on the web output.
Second, in the editor, the mandatory and sometimes optional expected information is displayed to the writers who then fill in the missing text. As an example, the editor can show you a grayed-out title field in which the author types in the title. Another example is the editor completing the excepted information for a hazard statement.
Finally, authors can adopt forms, where the expected information is provided in drop-down lists and tailored to the information model required by the organization.
Letting go of old tools
Others will embrace the new guidelines, editing tools, and systems without a look behind, however, changing tools and format can be difficult, especially for those who consider themselves experts with their current tools or systems.
Real change management and empowerment are crucial for those who feel they have most to lose with the change.
Ownership does not equal authoring
CIDM has made several great surveys and presentations about the sense of ownership and responsibility developed by content authors. When the content is modular and different people write content, then the authors should:
- reuse content crafted by someone else
- refrain from adapting that content for styles or personal preferences
With modular content, the final document is a combination of topics that are written by different team members. Responsibilities can be split between the different parts and the entire information object, where the document owner is not necessarily the document author.
Organizing with a sustainable framework
The best way to organize work and content with multiple authors is, therefore, to organize a framework for writers. Obvious and typical examples include:
- Create a DITA style-guide and enforce it with rules and formal reviews
- Use template topics and maps for authoring guidance
- Document your content lifecycle and status
- Talk with your information architect, whether adding constraints or specializations will help the authoring team
- Organize the team: who, what, when
Depending on your tools, these can be enforced with rules and formal reviews. Each of these points, of course, should be understood and agreed upon within the team.
Just starting with DITA? Keep an eye on these symptoms
Although structured authoring makes it difficult, it is still possible to write bad content with DITA. Adopting the standard will not make a difference if you do not keep an eye on things. Peer reviews are efficient, but the following list provides several symptoms that mean things are going wrong:
- So many conditions in the content that it becomes unreadable for authors
- Big blobs of text with no inter-title
- So many links you cannot get to the source of the reused content
- No semantics or no tags in your content
- All topics are untyped topics (no minimal separation in tasks, concepts, references)
- No guidance for writing, no style guide, no templates
Further guidance
Help is available on-line and freely from the OASIS committee publications and in the specifications themselves. You can also:
- Read a book such as the DITA Style guide or DITA Best Practices
- Try a self-learning website
- Attend training and workshops
- Try out sample content
This post ends the series of articles, based on the presentation “DITA Surprise! Unpacking Authoring Practices” delivered at the DITA Europe 2019 conference.
—
This blog was originally published in CIDM’s newsletter CIDM Matters.
