Find out the benefits from treating docs like code
What is Docs Like Code
How to standout in the technical communication industry.
Docs Like Code, also known as Docs as Code, has been a recent trend in the technical communication community. Anne Gentle has even written a book by the same title, “Docs Like Code”. More technical writing jobs are being created in the software industry and having this skill set will make you a better technical writer.
Treating documentation like code means that the documentation should be stored in some sort of version control system, like Git. The documentation should go through a review. The documentation tool-chain should be automated. To put simply, the documentation process goes through the same process code goes through.
Treating docs like code works best with a team of writers or reviewers, although it isn’t necessary. Lone writers can benefit from the docs like code approach. There is still utility in committing documentation to a version controlled system, albeit you lose out on the collaborative aspects of Git.
Benefits of the docs like code approach include promoting a form of collaboration.
Collaborating with teammates on branches ahead of releases help make sure your documentation has the most accurate information suited for your audience before the release of a new feature.
It is also easy to share your documentation with reviewers, stakeholders, and SMEs treating your docs like code. Reviewers are allowed to check for accuracy on the branch. Stakeholders and SMEs can see if the branch represents the new feature correctly and can add additional comments before the release is live. This is an easier method to check for technical accuracy as the documents can live in a production branch of the documents.
The automation of the docs like code approach means you can see your changes quickly. One technique is to use Continuous integration and continuous delivery or CI/CD.
CI/CD is a coding philosophy that aligns with the agile methodology to enable teams to focus on code quality due to the automated deployment method. Consistent and automated builds will help make more frequent code commits which leads to quality documentation and collaboration. I believe writers should be focusing on writing and not on the tools to build the documentation.
If you do decide to open-source your documentation, it may feel like you’re giving up a little freedom; however, I would argue that the documentation is for your audience and not for you, the writer.
Opening up your documentation allows for more people to see your docs and give input. I find most people are willing to share what works best for them. Sharing that knowledge can only strengthen your documents and help put focus on inaccurate or out of date documents.
The feedback given from places like GitHub helps everyone in the end. Your docs get more accurate, users can help find wholes in the document, and everyone is learning. I find that the most often asked for feature in the docs are examples. Users love to see real life examples. It is easy to put focus on examples when your users interact with you on a daily basis.
I would suggest reviewing every pull request and issue. Communicating quickly and often with your users will let them know their time isn’t wasted.
The user’s experience should be the first thing to take in consideration when creating documentation. Using a docs like code approach solves a lot of issues users experience. Writers are able to spend more time writing and less time worrying about the build process when docs are treated like code. The documents are updated more often and by user’s contribution.
What are your thoughts on the docs like code approach?