Continuous Documentation Delivery

By Sripriya Govindarajan

Introduction

Most companies are adopting the Continuous Integration (CI) and Continuous Delivery (CD) approach to stay on top of the business game and release new features to the market in as little time as possible. The Agile methodology and its manifestos help with achieving this goal seamlessly.

Before diving into the subject of discussion, let us first understand what CI/CD means and its benefits.

Continuous Integration (CI) – refers to continuously adding new features or fixes to the product in short intervals. The CI process is governed by specific rules, including manual and automated processes, to develop small, sizeable, and deployable software.

Continuous Delivery (CD) – refers to delivering the developed software to the customers at the end of every CI cycle. The CD process usually involves a manual intervention, where a user releases the new piece of software with a click of a button.

Continuous Deployment (CDep*) – refers to automatically deploying the software. The CD and CDep are usually used interchangeably in many discussions and as synonyms to convey the same information. However, there is a difference between the two processes. The CD process involves a manual intervention to deliver the software, whereas the CDep automatically delivers the software without any human intervention.

*CDep – The abbreviation used here is not industry-standard. I have used it to differentiate the two delivery options specifically.

Now that we have understood a CI/CD process, let us see how we can use it in Technical Documentation.

Continuous Documentation

In the Agile Scrum framework, Technical Documentation is usually placed one Sprint behind schedule or even worse, only during the last Sprint leading to the combined delivery of all the features developed in that release. Is there a problem with this approach? A stern YES, I would say! Let us see why.

• We write a piece of documentation to support a feature or fix a bug that needs to be released in parallel to the software to keep the documentation relevant. After all, there is no point in releasing documentation that is not up-to-date for software that is continuously evolving.

• When Technical Communicators are involved at the end of a project cycle, there is an unending effort versus time-to-market pressure, leading to low-quality, incomplete documentation, which is less searchable and findable. RESULT – an unpleased customer!

• Most often than not, the Developers and Subject Matter Experts (SMEs) involved in developing and testing the features move on to different projects and are unavailable to help the Technical Communicators with their questions simply because of the lack of time.

Can we think out-of-the-box and find a solution? Enter – Continuous Documentation Delivery or CoDocs

What is CoDocs?

CoDocs is a methodology that continuously creates, maintains, and delivers documentation just as code. We are hearing a lot about Docs-as-code these days and that many companies are already using it. But arguably, most of those companies or teams are not using it correctly or not leveraging the full potential of this approach. So let us dive deep into the subject to understand it better.

So, as mentioned earlier, CoDocs allows you to create and deliver documentation when it is of utmost essential, that is, deliver it to the customer along with the new feature or a bug fix.

To achieve this goal, we must adhere to the following principles:

 
1. Include the Technical Documentation phase in the CI/CD pipeline.

2. Add Technical Documentation completeness in the Definition of Done (DoD).

3. Invest in simple but compelling tools to help integrate and deliver documentation products.

4. Collaborate with cross-functional teams to deliver high-quality products.

5. Publish the content, gather feedback, and iterate if necessary.

Approach and findings

To support the idea cited in the earlier sections, I have detailed a viable approach and some of the key findings as described in the following sections:
Approach

Just as in code, we must follow the CI/CD pipeline as shown in the following image and process to deliver documentation continuously:

1. Create a repository to store the topics. We can use GitHub, Perforce, or any repository that the Development team uses to easily integrate with the builds.
   
   
2. Write individual topics that are small and shippable based on the user stories. We can use simple text editors to write the content. Tools such as MkDocs and Sphinx help you write effortlessly and support YAML or JSON formats.
   
   
3. Review the topics following the Self > Editorial > Developmental review process. We can integrate Linter tools that can automate the checks for self and editorial reviews, which would include checking for spelling mistakes, grammar, broken links, and styling issues.
   
   
4. Publish the topics after the topics are reviewed and signed off as part of DoD. We can use an intermediate file converter such as Pandoc to convert the files from Markdown or any other format to HTML-readable static files and upload them to Wiki.
   
   
5. Iterate on developing the content if changes are suggested.

Key findings

The following are the key findings and benefits of CoDocs:

1. Leverage the benefit of Developer tools and produce code-compatible documentation.
   
   
2. Reduce the time to market for delivering documentation.
   
   
3. Improve and deliver high-quality documentation at the end of the release through customer feedback, iterations, and continuous integration.
   
   
4. Automate some of the editorial checks for repetitive mistakes.
   
   
5. Handle versioning of topics.
   
   
6. Automate content deployment.

Conclusion

A piece of software is only good as the documentation it supports. Therefore, we need to produce and deliver quality documentation that is relevant, searchable, and available. The present-day scenario of involving the documentation teams after a sprint is closed or towards the fag end of the release will only cause obsolete content. To conclude, I strongly recommend that technical documentation be delivered the CoDocs way.

 

Key Takeaways

• Create relevant documentation
• Create a synergy with software development
• Automate review processes
• Automate deployment
• Iterate and deliver useful and findable content