There are many key factors that make DITA-based technical documentation complementary to Agile-based product development. Here are 10 reasons, among many, why DITA and Agile make a great partnership:
- Topic-based approach in DITA assists with incremental development: One of the tenets of DITA is content reuse, encouraging technical writers to “write once, use many”. This also means that there is no need to re-write what already exists—a writer can simply reuse entire topics, paragraphs, or phrases used elsewhere thanks to reuse mechanisms within DITA. This enables writers to easily keep up with the rapid pace of development changes.
- Agile user stories maps well to the task topic type in DITA: Scrum-based Agile often calls upon user stories to help craft development efforts. These often take the form of various procedures that users will want to accomplish. This format fits nicely with the DITA task topic type. One common practice I found when interviewing Agile-based DITA technical writers was for them to encapsulate the concept as the context for a task instead of writing separate concept and task topics. Additionally, Agile “epics” are collections of related user stories that comprise the complete workflow for a type of user. From a DITA standpoint, epics can be used to help refine audience-based conditional processing of content, or maps (chapters) within a bookmap when an epic story hierarchy exists.
DITA 1.3 added troubleshooting as a new topic type, designed to provide specific solutions to scenarios that are likely to arise, and how to solve them. This new DITA topic type is perfect for writers looking for a troubleshooting option for user stories where a task may not be an appropriate solution.
- DITA best practices advocate that content is focused squarely on the user: Technical writers are able to provide early feedback on products through their active use of the product. In this way technical writers often become an advocate for users; this in turn helps define realistic user stories. The constant change and iterations of content over multiple releases forces a change in the typical writer’s mindset from “document everything” to instead “document only what the user needs”. Again, the granular, topic-based nature of DITA helps make this possible.
- Individual topics can be counted, allowing for documentation project measurement: In a typical Scrum-based Agile environment, everyone involved in a project gathers together to discuss progress in regular meetings. Using a traditional DTP-based approach, all that can typically be reported is the word count or the number of chapters completed since the last sprint. With DITA, it is possible to match development features to individual topics, making it easier to report in a more realistic manner on documentation progress. If a Component Content Management System is used, workflow status—draft, in review, done, etc.—can also be measured and reported at the Scrum meeting.
- The DITA best practice of minimalism reduces “waste”: One of the key concepts of Lean Management—an Agile methodology—is to reduce waste wherever possible. This is encapsulated in the Japanese term “muda“. In the case of documentation, this refers to content that is unnecessary in order for the customer to use the product. It serves as a check on technical writers from writing “filler”—typically background or marketing-related content that a user does not need in order to accomplish a particular task or action with the product. One of the philosophical underpinnings of DITA is minimalism, which similarly tells writers to pare content down to its essentials.
- Topic reuse improves content consistency: The various content reuse mechanisms in DITA—topic, conrefs, and keys—contribute to greater consistency in documentation output generated within an Agile environment. Due to short deadlines and time constraints within Agile environments, it is more expedient for technical writers to reuse content where it exists, and DITA provides easy mechanisms for accomplishing this. In many business environments, if you have a topic and it has been reviewed and approved, and you want to reuse it elsewhere, it does not have to be sent out for review again, as it has already been done. (The exception are regulated environments where all content must be reviewed in context, but even here content reuse speeds up the approvals process).
- The separation of content from formatting saves time: Thanks to the separation of content formatting built into DITA, technical writers can focus on creating content rather than formatting it. This can save a considerable amount of time. An informal survey I did several years ago with a team of technical writers using a popular desktop publishing software to produce their documentation showed that roughly half of their time was spent formatting content. That time can now instead be put towards writing more Agile content in a DITA-based environment. This also eliminates the time wasted when subject matter experts comment on formatting instead of the content they are supposed to be reviewing.
- Agile encourages continuous feedback; topic-based review is easier: It is simply easier for developers to review a topic rather than a chapter produced by a DTP tool, shortening review times. In this way, documentation can also support broader communication between teams, customers, audit processes, etc. Work cycles are faster, and documentation feedback becomes more critical. One of the technical writers I interviewed for this article told me that Agile developers “left no room for procrastination, so this was an easy way for them to check this off their own task list.”
- DITA short descriptions direct users to content: Writing short description for DITA topics is already considered a best practice, and it is arguably more so for Agile-based content, as it provides a means of progressive disclosure as to content relevancy for users as they search for information. Often a short description can be similar to the intent of an Agile user story, where: “user x can do y based on z”.
- DITA makes publishing on demand to multiple formats straightforward: The DITA Open Toolkit is designed to produce documentation outputs in multiple formats, including HTML, WebHelp and PDF. It is also possible to flexibly produce documentation at the chapter or individual topic level on demand. Waiting for documentation deliverables is rarely a bottleneck in a DITA-based process.
The original version of this blog piece was published as a portion of an article for tcworld Magazine back in December 2016.
