DITA: Or How to Love Technical Documentation

Automated PDF (&/or online content) production from a single source to multiple outputs is key for any modern information purveyor—and key really to an efficient software development house as technical documentation is quite often not thought about until (too?) late in the process—must be shipped with any software product meant for users.

Professional software publishers like Autodesk know this, and still expend time and money for this job to be done, but sometimes smaller businesses are either way too cost conscious in the short term (as costs will inevitably accumulate later due to poor documentation) or just do not understand its importance.

Very simply stated: what’s the use of a feature designed by 5 engineers with Master’s degrees in computer science if the person actually paying for the software to use cannot figure out what the feature is for or what to do with it?

This is where rigorous technical documentation comes into play—using interviews with engineers, project managers & product managers, as well as ideally as much exposure to end users as possible, a knowledge of the market/discipline the software is destined for, complete technical review cycles, time for production, indexing, and quality assurance for the documentation similar to the process performed on the code itself.

Modern structured formats like XML/DITA should be used for large projects, and all files, folders, and links maintained in a clean and logical manner, especially for updating and localization purposes.

While applying this level of forward-looking-sophistication can seem at first blush to be expensive and overkill for a typical CEO of a software company—it would be beneficial for anyone in such a position to realize just as their codebase will grow (often exponentially) and new tools and methods will have to be brought to the fore; so too will the doc set grow and thinking about implications earlier always saves time and money down the road.