We look at the pros and cons of using the DITA standard, and the alternatives.
At the Write The Docs event in London last night, Gergely Imreh presented Resin.io’s approach to customer-driven docs – documentation as self service support. Resin.io is a software company that provides Linux containers to the Internet of Things. It sees itself as a support-driven organisation, and so documentation is very important to them.
The discussions at the end of the talk were around which type of platform is best for developer documentation.
Resin.io uses an in-house system, based on Markdown and a flat-file publishing tool. They build pages from “partials” (snippets of re-usable chunks of information) to create “parametric information”. Pages can be built to match different criteria. For example, using Resin.io on a Raspberry Pi and Node.js. It provides an authoring environment that is easy for developers to use; it doesn’t require a database-driven CMS; and the content can be treated in a similar way to the code. The challenge with this type of system is getting it to scale. The “intelligence” of the system is through storing content in folders and using scripts within pages. As the grows, they are finding it harder to manage.
Gergely said he’d like see if a wiki-based system would work better. Content would be easier to edit, as pages would be more self-contained.
Kristof van Tomme suggested using a database-driven CMS. Pages would be built “on the fly”, by the CMS. In this situation, the “intelligence” of the system is through metadata wrapped around each topic and the database software that’s managing the content. The downside is it can mean there might be challenges in moving it to another platform at some stage in the future. You also have to manage the database and protect the CMS from potential hacking.
Another suggestion was to use a semantic language to write the content. This could be AsciiDoc or DITA. In this situation, the “intelligence” is placed in the topics and with the writers: they “markup” sentences or paragraphs for each applicable parameter, such as audience and computer. These can be published as flat files or be managed by a database. This approach is scalable and tools-independent, but it requires much more work by the writers.
What’s best depends partly on your view of the problem. Is it a information design problem, a software problem, or a data management problem? There are pros and cons to each approach.
In the Agile Technical Writers forum on LinkedIn, one of its members posted this question:
“I need to create an contextual online help for an complex web tool (ok, that´s not that hard). The customer must be able to add some specific job instructions to this online help by himself. The customer part must not be overridden when the online help is updated.”
LinkedIn’s forums provide limited functionality for long replies, so I thought I’d answer the question in more depth on our blog.
There are three main approaches you can take:
- Appending content to the bottom of a page
- Embedding empty placeholder topics within topics (which the client can use to add content)
You can also simply link to an external topic. However, in this case, they wanted the user content to appear with the official content.
In the DITA authoring standard, transclusion is called content referencing (or conref for short). It enables you to insert information from one topic into another. This means you can add customised content to a topic without having to make any changes to that target topic. You specify how the information is pushed into the existing topic: Insert the information just before an element; insert the information just after an element; or replace the information contained in an element. One of its strengths is, if you are adding new items to a list of steps, the list will renumber automatically.
Here is an illustration from our DITA training course:
The downside is writers need to be familiar with DITA, or be given a template to use.
Appending content to the bottom of a page
A common approach is to enable users to add comments and additional information at the bottom of each topic. This is the approach taken by tools such as Confluence, Mindtouch and MadCap Pulse.
This can work well. However, the information can be missed by it being at the bottom of the page, and if there are too many comments.
Embedding empty placeholder topics within topics
Another approach is to have empty topics within each topic. The two topics can be concatenated (joined) together to form a single topic. The client can add any client-specific content into the empty placeholder topic, so they don’t need to touch the topic containing the official content. This is sometimes called embedding topics within topics.
Here is an example of how local branch information is added to official documentation on fire safety procedures:
The advantage of this approach is that it can be done with simpler authoring tools than DITA (like markdown). The disadvantage is that you may not be able to preview the final topic (to do that, you’ll need to generate the whole document), and it won’t work as well for inserting content into numbered lists.
Do you use a different method?
Please share your thoughts below.
Judging by Social Media last week, there were many strong opinions at the tekom tcworld conference towards the DITA authoring standard and the associated tools. It seemed, as the philosopher Swift once said, “Haters gonna hate”, and, by inference, “Hypers gonna hype”.
Eliot Kimber provided an interesting summary in a post to the DITA users group forum (Trip Report: Tekom 2015, DITA vs Walled Garden CCMS Systems):
“For background, Germany has had several SGML- and XML-based component content management system products available since the mid 90’s, of which Schema is probably the best known. These systems use their own XML models and are highly optimized for the needs of the German machinery industry…These products are widely deployed in Germany and other European countries. DITA poses a problem for these products to the degree that they are not able to directly support DITA markup internally, for whatever reason, e.g., having been architected around a specific XML model such that supporting other models is difficult. So there is a clear and understandable tension between the vendors and happy users of these products and the adoption of DITA…
…It’s clear to me that DITA is gaining traction in Europe and, slowly, in Germany but that the DITA CCMS vendors will need to step up their game if they want to compete head-to-head against entrenched systems like Schema and Acolada. Likewise, the DITA community needs to do a better job of educating both tools vendors and potential DITA users if we expect them to be both accepting of DITA and successful in their attempts to implement and use it.”
This may have led those who are asking, do I need DITA?, to come away from the conference more confused than before. So, we thought it might be useful to provide a rough guide to whether it’s worth adopting DITA:
You probably don’t need DITA if:
- The way the content looks to the user is the most important issue.
- You have fewer than four writers.
- You write narrative content.
- You have limited budgets for tools, training and migration.
- You don’t have the time to deal with the issues around changing working methods.
- Your content has a “shelf life” of less than two years.
- You use a lot of graphics with annotations.
- You need to customise outputs [added] for individual documents [added] (such as PDFs).
- The cost of migrating existing content will be expensive.
- You want the presentation layer embedded with the content layer.
- You don’t want to work within strict rules regarding how topics are written (where content is marked up semantically).
- You need to use the tools used by developers or the marketing department.
- You want a simple information architecture.
You might need DITA if:
- You need to write to (and enforce) a standard.
- You need to localise content into many languages.
- You have more than four writers.
- You want to write semantically.
- You need a more efficient authoring, [added] reviewing [added] and publishing process.
- You create many variations of the same document.
- You want intelligent content that can adapt to different users and contexts.
- You are spending too much time on formatting content.
- You need to re-use content in different projects and different contexts, and make those topics accessible to other writing teams who might want to re-use them.
- You need to establish a controlled vocabulary and taxonomy.
- You want content validated for consistency.
- You want automated publishing.
You probably do need DITA if:
- You need to share content with other organisations.
- Your content will need to last more than 30 years.
- You want content to be stored in an open data standard, independent of any tool.
- You don’t want to be tied into a specific authoring tool, content management system or publishing/rendering engine.
- You need transclusion (where an element can replace itself with the content of a like element elsewhere) across a range of media.
- You want to have a way of generalising back to a common standard.
Do you agree?
Please share your thoughts below.
We’ve updated the video recordings in our online DITA course, and today (28th March) we’re uploading the new recordings to our learning area. This means the course will be down for a short while today.
Mike Atherton, Lead Instructor at General Assembly London, tweeted a link to a 2011interview with Ted Nelson on the future of text, document abstraction and transclusion.
Ted Nelson is one of the pioneers of information technology. He has been credited as being the first person to use the words hypertext and hypermedia (although he denies this), transclusion and virtuality.
It’s an interesting description of how content should be independent of format and media, so it can be portable, re-usable and presented in ways that best suit a reader’s needs.
It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.
According to the Oasis DITA standards committee,
Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.
The user would see a topic that looks roughly like this:
Continue reading “Writing troubleshooting topics”
Craig Wright emailed us to let us know he has posted a review of our DITA elearning course (see Review – Cherryleaf DITA e-Learning Course).
His conclusion was:
The Cherryleaf DITA course ticked a lot of the boxes for me:good content, good value, and available without having to travel to the South East. The introduction to the key DITA areas was presented very well – I have read similar information in books and online, but I was able to absorb it much better through the e-learning course.
Thank you Craig!