Have you ever wondered why everyone talks about automation of EVERYTHING in technical writing? Is that really important?
Well, let me share my story about that.
A few months ago I was consulting a product area. They were getting ready with the documentation for their first release. Everything was running smoothly, and the documentation team was documenting feature after features, as needed, as planned. The release date of the software was approaching and the team was getting nervous - have we documented everything? Is language ending done on time? Have we validated all the documentation?
And again, everything seemed to move according to the original plans and there were no signs of concern.
As there were only a few days remaining before the official delivery to customers, the management authorized the team to start working on the next version of the product.
The team started work on the next documentation release, switching focus to it.
The date of the shipment to the customers came. It was a few hours before they were ready to announce the delivery of the new products when the message came in - one of the features had a severe issue. The management decided that we cannot proceed with the delivery to customers before the issue is fixed, so they have taken out this module of the software functionality. The delivery to the customer will proceed as follows but the documentation we provide must be removed ASAP! The documentation team has 2 hours to do so!
Well, that’s a challenge! Rewriting and re-publishing the document set is time-consuming - you cannot just go on and take the information out that easily - you need to read through that content, analyze the references between the documentation, make sure you do not end up leaving broken pages in the document!
To make things worse, the same documentation was already used as a basis for the next release - if we simply remove it in a hurry, we will have to start the work over the new release from scratch - again - and lose all our work so far!
How would you solve that?!
Luckily for us, our DITA XML -based authoring environment allowed such flexibility. We’ve managed to quickly introduce a new profiling attribute value. We named it “internal” We’ve used that profiling value to tag all content that was not supposed to go live on that day.
It took us a couple of minutes to cross-check for content mentioning the problematic feature. We’ve also profiled the DITA maps and DITA topics that were meant to describe the feature.
Once we were ready, we’ve retriggered the publishing process with “exclude” profiling logic and re-deployed the documentation outputs on time! All links were with an automated generation strategy, thus they also got automatically updated to only content that was available during the build, allowing us to be sure no broken links are produced.
We’ve managed to deliver on time! One more time, we were saved by the flexibility provided by DITA XML and the automated build and publishing processes!