A feature does not exist until it is properly documented. In my already-long career as a software marketer, how many times have I heard this? And rightfully so: good user documentation is the cornerstone of proper software adoption, and the key to many aspects of the sales cycle (and beyond):
- During evaluation or proof-of-concept, users must not waste time learning how to use the software, and they must gain confidence that actual users (who may be less qualified than the evaluators) will be productive.
- Once the deal is closed, the crucial adoption begins, and if unsuccessful, it can result in software becoming shelfware.
- At the time of upgrades, knowing how to transition, which features have changed, which new processes must be implemented, is critically important.
- When the time comes to renewing the subscription contract or the support contract, actual rate of adoption and feedback from users will be carefully measured by the client.
What is good documentation?
In a not-so-distant past, good documentation primarily meant comprehensive documentation, covering all features and capabilities of the software. This documentation was provided as books -- traditionally printed, but more and more delivered in electronic PDF format. Online, contextual help could also be provided with direct bookmarks from within the software itself.
More and more, this comprehensive documentation needs to be augmented with videos, how-to tutorials and interactive wizards. Its production is no longer the sole realm of a dedicated technical writing team, but a number of subject matter experts can contribute to it, provide their expertise and their actual usage stories and advice. And there is a wealth of sources from which to get this content, including Wikis, forums, etc.
From monolithic manuals to componentized documentation
The first change that happens in software documentation is structural in nature: we are no longer dealing with monolithic books but individual content components, which can then be arranged in many different ways:
- As a comprehensive book, containing all topics.
- As a custom book, built for the needs of a given user, or for a specific configuration.
- As how-to procedures, showing a series of components arranged in logical order.
- As chunks of content, easy to search and retrieve.
- And many more.
In a way, documentation is going the way of microservices, divided into independent units of content that are combined as needed to enable usage.
Continuous publishing
Most software is no longer released twice a year, but depending on the agility of the vendor, every few weeks to every dew days, even several times per day. Documentation for these new or updated features therefore needs to follow suit, and Continuous Publishing becomes part of the Continuous Integration process.
Every unit of content goes through a devops process that is very similar to its software counterpart, being written, reviewed, checked, and integrated into a delivery repository that is published at the same time the updated software is released.
XML or Markdown?
Most documentation formats today are XML-based, or closely derived from XML. A schema-less way of writing and organizing documentation is starting to gain traction however. In the same way JSON is now used for microservices and component interoperability, languages such as Markdown lighten the documentation complexity and make it more flexible.
Documentation is not just supporting content for software, it is an integral part of software. It is therefore no surprise that the same techniques that make software development more agile and efficient, would also apply to the production of documentation.