Find out the benefits from treating docs like code

What is Docs Like Code

Photo by Clément H on Unsplash

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

Reviews

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.

Automation

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.

Collaboration

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.

Summary

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?

--

--

--

Technical writer for AWS. I enjoy documenting my thoughts and sharing ideas with others.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Rafay Startup Package

CSS (Cascading Style Sheets)

Low-Latency Distributed Messaging with RocketMQ — Part 2

Challenges of Learning

The Future of SQL Query Engine

Cloud Custodian: Easy way to explore instances in AWS cloud

File Transfer from Windows/Google Drive to VM (Ubuntu)

Automate datain your database with Faker

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Patrick Rachford

Patrick Rachford

Technical writer for AWS. I enjoy documenting my thoughts and sharing ideas with others.

More from Medium

Why Building Software Should Always Be an Organic Process

Why You Should Implement No-Meeting Days

How I automate my changelog with imdone!

The 5 no-code most typical mistakes and how to avoid them