The Docs-As-Code Workflow

Docs-as-code stands for the idea that you treat your documentation just like any other source code. In practice this means:

• You store your documentation in source control in a format such as Markdown
• Deployment happens automatically through your build system
• Collaboration and review happens through version control (for example in GitHub)

Doctave is built with these ideas in mind.

Storing docs in source code

With Doctave, your documentation lives in your source control repository. You own your data and decide when it gets sent to Doctave.

It also means using a some form of markup language to write your content. There are a many choices to choose from. Doctave supports Markdown (CommonMark to be exact).

The core idea is that you separate your content from presentation.

Finally, all your editing happens locally on your machine. You should be able to preview what your final documentation looks by invoking your documentation toolchain and building your documentation site. In Doctave this is done with our desktop app, which is an all-in-one preview environment and a linter.

Deployment

Deployment of your documentation should be an automatic process. Usually this means setting up your CI/CD pipeline such that a merge to your main branch causes a deployment to happen.

For more advanced setups, you can create preview environments so that your team members can interact with your submitted changes before they get released to your readers. Doctave supports this workflow out of the box. In fact, you can travel back in time to go view any previous build of your documentation.

It's straightforward to include Doctave in your CI/CD pipeline. The integration can be enabled with a single line of code: invoking a script that bundles your documentation and pushes it to the Doctave servers. Doctave will either update your live documentation or create a preview environment, depending on which Git branch the push came from.

Collaboration

Once you have made your changes locally, you usually want to send your changes to be reviewed, just like you would do with code. This review process commonly happens in a tool like GitHub or GitLab through pull requests.

Doctave assists in this by creating preview environments for all your changes, making it easy for your team members to see what your documentation will look like once your changes are applied.

But why?

We're pragmatic folks at Doctave and aren't going to claim that docs-as-code will solve all your documentation issues alone. We believe it's a great workflow to use in many cases. Especially for technical documentation where the people in charge of documentation are technical themselves and are comfortable using a software-development workflow. If this doesn't apply to you, docs-as-code may not be the right choice for you.

However, there are some good reasons why you should consider docs as code if you are a company with technical documentation authors.

• It's easier to keep your docs and code in sync
• You can use the same workflow for docs and code
• Developers will find it easier to contribute changes
• Automation becomes easier
• Versioning can be done in branches

We've written a longer post about the benefits of docs-as-code which we recommend.