Monthly Archives: August 2017

Do We Need More Docs for this Release?

Most technical authors ‘tune in’ to development projects to know what needs to be documented in a release. This is because the required content is not always known up front.

Product features in most software companies are developed using some form of Agile. There has been debate about how technical writers integrate with Agile, a process which is largely driven by developers. For example, at the end of 2016, the Write the Docs meetup group in collaboration with the Government Digital Service, organised an entire conference based on this topic.

This ‘tuning in’ on the part of the author often involves attending daily standups and sprint planning sessions. However, technical authors are very often welcome in these sessions.  Sprint planning sessions are largely developer-centric. Developers would analyse each story, investigate dependencies, and create estimates on how long it would take to produce the work. But when the author contributes by announcing their own documentation estimations and documentation stories, it always feels like a solo task. The developer often doesn’t know the process a author takes to produce the content.  And sometimes the author doesn’t know either!

Understanding the type of release and having an approximate idea of the documentation needed helps. When releases take place on a regular basis there is often a pattern. For some releases there is too much documentation to be covered, while in others hardly any descriptions are needed.

These release situations are summed up in the following diagram:

doc comparison



In this scenario, developers make key under-the-hood changes to the software product to boost performance and/or security. Developers may provide descriptions, e.g. in specifications, which are often highly technical and won’t benefit anyone except fellow developers in the same team. There is a dependency in that the author must research the content, but in a time efficient manner (as documentation is often not needed). Releasing content to customers could also be potentially dangerous as it may expose vulnerabilities in the software.


In this scenario, key features are released that end users will benefit from. The work could even  be an extension of a product, such as a new API or user interface tool. Technical authors often need to produce detailed and varied material that can include document reference material, marketing content, user guides, and setup instructions.


Minor code changes are done in this scenario, but the impact on the end user may be significant.  A single feature may require changes to multiple docs. These releases are often quite challenging for the technical author and they should communicate upfront with developers the known documentation requirements and estimations.


In this scenario, few features are released and the documentation required is minimal. Instead of writing about new features, authors could spend time revamping the writing style, boosting the navigation of the documentation pages, creating meaningful overview diagrams, or conducting customer surveys. The features and fixes produced by the developer have little impact to the customer. This is often code refactoring work that may pave the way for significant future development. For the most part, we can work independently from the development team for these releases.

I have found that using the above matrix beneficial in planning documentation for different releases. It has also helped me to decide whether or not to attend sprint planning sessions.

Lastly, feel free to view my presentation that I delivered at the aforementioned Write the Docs conference on slideshare that has details of my views on the technical author in the Agile process