# Writing Sample: Docs as code - Why bother, and how to start writing documents as code

You should read this if you are a technical writer and want to work better with development teams. By the time you finish reading this, you should be able to:

* explain the process that a docs as code approach entails.
* have a plan to transform the documentation process in your organization.

This article assumes working knowledge of [Agile software development](https://www.smartsheet.com/understanding-agile-software-development-lifecycle-and-process-workflow) and [technical documentation](https://medium.com/@kesiparker/the-technical-writing-process-6b5939a23555) processes. If you feel like you could do with a refresher then the links above are a good place to start.

## What is docs as code

[Docs as code](https://www.writethedocs.org/guide/docs-as-code/) refers to a philosophy that you should be writing documentation with the same tools as code, and within the same process as software development.

These tools include, but are not limited to:

1\. Issue tracker tools such as [Jira](https://www.atlassian.com/software/jira)\
2\. Version control tools such as [Git](https://github.com/)\
3\. Plain Text Markup languages such as [Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)\
4\. Where possible, a docs as code approach also entails automating review processes and other software development best practices such as [Continuous Integration and Continuous Deployment](https://thenewstack.io/continuous-documentation-in-a-ci-cd-world/).

## Why use docs as code

The most common way that documentation is created in most organizations is by using a what you see is what you get (WYSIWYG) Content Management System (CMS). Once documentation teams have gathered information from developers, they write it up and post this information to a website using a CMS like WordPress, Squarespace, Madcap flare and so on.

Let’s look at how a docs as code approach improves upon the standard approach:

| The Standard Approach                                                                                            | Docs as Code                                                                                      |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Development and documentation teams are completely siloed.                                                       | Documentation teams work in the same process and use the same tools as development teams.         |
| Documentation often comes after development which means you can’t release your docs as you release your product. | Documentation is written alongside new feature development, not after.                            |
| <p>The actual writing of documentation is almost</p><p>never owned by development teams.</p>                     | Developers take ownership of documentation when they can treat docs the same way as they do code. |

[Research on best practices for documenting code ](https://idratherbewriting.com/learnapidoc/docapiscode_research_on_documenting_code.html)has shown that docs should be written when code development is still fresh in the developer’s mind. When developers are asked to recall details that are no longer at the forefront of their minds, the quality of information that you get, and consequently your customer facing docs are likely to suffer.

## How does it look in practice?

To keep it simple, let’s assume your company follows the typical Agile software development process. Here is what a docs as code approach would look like in parallel with Agile software development.

| Agile software development | Docs as Code                                       |
| -------------------------- | -------------------------------------------------- |
| Define new features        | Define documentation deliverable                   |
| Write code                 | Write docs in Markdown and maintain content in Git |
| Build an executable        | Push content to a website                          |
| Test code                  | Review and run validation checks                   |
| Release new features       | Publish docs                                       |

## Tools and practical recommendations

Much like you need a translator to speak to someone in another language, you need a website generator for docs as code. A website generator interprets Markdown (docs written as code) to a readable format (a website) for your end users.

There are many website generators available, but one of my favorites is [Gitbook](https://www.gitbook.com/). Gitbook brings the best of both worlds together – enabling developers to push first drafts of content from tools that they love, and enabling product teams or technical writers to review and publish from a state of the art wysiwyg environment. You can connect your account to git and publish directly from there as well.

## So what's next?

Whether or not you are ready to adopt a docs as code approach in your team will depend on the appetite for change in your organization, ability to self-train and many other factors. I recently started implementing this approach for one of our teams. We have started building in the process and are slowly getting rolling out the tooling, including Gitbook. If you want to try it out for yourself, I recommend you start by:

1. Editing a simple [Markdown doc](https://dillinger.io/).
2. Signing up for a free account on Gitbook and following their [guide](https://docs.gitbook.com/) on how to get started on your docs as code journey.

There are so many [success stories](https://pronovix.com/blog/treat-docs-code) out there, so why not start yours? Good luck, and happy writing!
