Docs as Code

• Thu, Jan 17, 2019
• 3-minute read

Documentation in the software development world often and usually means documenting a finished product. That means that the engineering team spent a few months creating some new software product or a new feature for an existing product, then the QA team would test the product, and then some TW would work on creating the User Guides, Architecture documentation, etc.

With Agile, engineering teams don’t work like that. Agile means that the team is constantly iterating the process of planning, developing, testing, and releasing a product. What they do is that they work on delivering small features and then work on new features or improving the existing ones, always delivering new small pieces of functional features.

As a TW working in an Agile environment, you don’t want to be sitting down until the team finishes the whole product to start documenting. To be able to work with the team at the same pace, you have to:

1. Request access to the code repositories.
   (You want to know first hand what is going on).
   It is way better if you can actually install the project on your local machine to see exactly how everything is working on the development process.
2. Review and document all the internal processes:
   • How to install the project.
   • How to contribute.
   • How the deployment process works.
   • Is there a CI/CD process implemented? Document it.
   • Is there an API? Document it.
   • Is there a working feature already? Or a new one? Document it.
3. Create a docs directory within the same repository that the team is working on.
   This enables you to participate with the engineering team following the same practices that they follow, which is a way of being an active part of the team.
   You can use different tools to help you keep your docs directory and treat Documentation as Code. Keep reading to find out which are those.

Treating Documentation as Code

Depending on what programming language or framework your team is using, there are different tools that you can use to be able to maintain your Documentation as Code.

These are some of the tools I’ve experimented with:

• Vue Press
• Docsify
• Gatsby.js
• Jekyll

All of these are basically Static Site generators that enable you to write your documentation in Markdown and convert it into a Static Webpage with cool rendering of your Markdown files. Plus, they work great with different integrations, such as Vue.js or React, and can be easily deployed to hosting platforms such as, Netlify, AWS S3, Github Pages, etc.

Cool. So, How do I do That?

In the next posts I’ll be writing about how to work with the previously mentioned tools and how to deploy them to website hosting services. Stay tuned!