Table of contents
Definition
Docs As Code (DAC) is the process of handling the creation and management of documentation [→] like you would code or software in general.
In software development, the creation and maintenance of software typically goes through a model known as the software development lifecycle. This process includes the planning, creation, testing, and deploying of the software. Different tools are used for each part of the model.
Docs As Code adopts both the model and some of the tools for the creation and maintenance of software documentation.
Use Cases and Examples
There are 3 key points to look at if we want to better understand Docs As Code:
Documentation platforms
Just like blogs a CMS-like [↗] system is used to host software documentation. A good third-party example is ReadMe.io [↗] and free and open source version Docusaurus [↗]
These CMS-like systems unlike mainstream CMS systems come with information architectures that look a lot different from a typical blog.
For example, most documentation contains code snippets and so special widgets are provided within the documentation to display formatted and colorful code. You can find some examples of these on my blog [→]
Most software companies create their own documentation platforms.
This is where the whole Docs As Code process starts.
Technical writers [→] will usually have to set up the documentation platform on their computers and have access to several folders within the platform codebase where they add their content in the form of Markdown [→].
One of the reasons the content is written in Markdown is because its syntax can be easily translated into HTML [↗]. This is particularly helpful because it makes it easy to render the documentation on the web.
Since they have the CMS setup on their computer they can see what the documentation will look like when it's finally hosted online or deployed as it's mostly called.
Authoring process
As mentioned earlier, the content in most Docs As Code setups is written in markdown and kept in a designated folder within the documentation platform or CMS.
There are usually other folders used to hold things like images and other asset files that form part of the documentation.
Contributions and collaboration to the documentation in most cases are managed using the Git Workflow [↗].
This Git Workflow involves the use of GIT [↗] as a version control [→] tool and an online repository service like GitHub [↗] or BitBucket [↗] to store the documentation. This also acts as a central point from where everyone goes to grab the most recent version of the documentation (finished or unfinished).
Review PhaseJust like with software development, there is the review and approval phase. In the case of DAC, this is simply known as the review phase.
Ideally, the writer will open up a Pull Request [↗], this is a request to ask that the changes or additions they have made be added to the main documentation.
Here other writers or editors can leave their comments and request further changes.
Once reviewed their additions and changes are accepted and merged [↗] into the main body of documentation and the next step is deployment.
A Pull Request is a well-known way in the software development world for requesting to add new changes to software.
DeploymentJust like with software code, once everything is ok, the last step more or less is to make the new changes available to the end-user or reader in this case.
This involves pushing out the updated version of the documentation platform containing the updated content.
If the developers of the documentation platform also made changes then they will push these changes out as well.
Summary
Using the software development lifecycle which is a tried and tested approach as part of the documentation not only improves the documentation process, it also creates a harmonic flow between the development of the documentation platform itself and its accompanying documentation (in most cases).
Here is another article you might like 😊 "Diary Of Insights: A Documentation Of My Discoveries"