You’re in the final stretch towards completing the documentation for a set of products when you receive some last minute changes.
Since all of your content was built using DITA XML, you quickly open the affected topics, make the changes, tag the content based on the specific models affected, publish, and send it for review.
And you are done! Or are you?
Components of Agile
- Welcome changing requirements, even late in development
- Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale
DITA XML was built for reuse and offers a perfect content development solution for an Agile team. But the short development times and constant delivery takes its toll on the writers – and the content. Often writers are left with little ‘on-time’ to plan or maintain content.
Which begs the question: In our haste to meet deadlines, are we creating more waste?
What is waste?
When content or topics are reused, more information is added over time to help identify the applicability of the content. For example, you may mark out sections of the doc that should be seen only in a specific model or release.
This can cause two potential waste scenarios. Either you spend more time figuring out where the content or topics belong and where it may be easier to create a whole new topic, or you have multiple topics talking about the same thing. In either case, you can end up contributing to documentation waste.
How can you eliminate or reduce documentation waste?
Create a Solution Matrix.
Customers no longer use products, they use solutions. With every iteration of a product, there will be tons of crossovers and dependencies. Hence, create a matrix of features and the products that support it. And maintain this Solution Matrix in a location that everyone can access.
Before you start working on a feature, a quick look at the Solutions Matrix can help you figure out who may have already created similar content or may be interested in the content you may be creating.
In Agile teams, use the release planning time to update and maintain the matrix.
Collaborate as you create content.
If you are creating new content and know there are other writers in your team who may need your content, notify them before you start work, and include these writers in the review of the content as well.
If you are looking to make updates to already existing content, notify the owner about the changes before make them, and include the content owner during the content reviews.
Involving other writers allows for issues and suggestions to be identified and managed earlier in content development, and reduces the possibility of mistakes. Writers in Agile teams can use planning and sprint meetings to identify topics that need to be updated, and other writers who will be able to help with the process.
Is it time to create all new reusable content?
Good writing is the core of all reusable content. Sticking to the basics of topic-based writing makes the content more portable and reduces the time we spend (or waste) trying to make it reusable.
- Focus on the content that’s required
- Think about the audience: what do they need?
- Generalize content where applicable
- Identify variance (audience, product, release) and separate it from common content
Know when to walk away.
Just because there is a similar topic, don’t feel you have to reuse it. If the variations in the content are significant, you’ll likely spend more time managing the variation than you would by creating and managing an entirely new topic.
Keep it clean and lean.
Most Agile teams use the last few sprints before the official release for regression. It’s a good time to do some end-to-end reviews of the content and some basic housekeeping before you start preparing for the next release. Look for duplication, filter metadata that is no longer required, and look for topics that can be retired.
By following some of the tips above, your content will be easier to manage, and leave you with more time for ‘on-time’ to plan your content. This will create a better experience for your team and better content for your clients.