Skip to main content

Docs Like Code

Overview​

Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code:

  • Issue Trackers
  • Version Control (Git)
  • Markdown
  • Code Reviews
  • Automated Tests

For the past few years, companies have invested in Documentation As Code. The process is simple: A developer owns a repository shared with the rest of the team, builds the application or service and keeps the code safe in the repository.

The developer also includes documentation as part of the repository, close to the code. Some documentation might be autogenerated if the code is well formed. The possibilities for performing this process are infinite. But all of them require internal process culture, and developers must in some way be strictly obligated to follow the process.

Another important key is the markdown syntax. Markdown files are powerful and easy to manage. The result is consistent, unified and beautiful.

The advantages of this process are many: version-controlled documentation, pull requests with code and documentation review, consistent design to documentation and a million ways to perform documentation with markdown syntax.

The disadvantage is the culture/process change where a developer may not think documentation is important.

Benefits​

  • Collaborating with contributors efficiently by keeping docs close to code or in the same system as code, with a source file concept and an output for deliverables.
  • Building documentation as repeatably and consistently as possible across multiple platforms. While typically done with open source tools, the main driver is not open source but open, repeatable, consistent collaboration.
  • Applying software development tools and techniques to documentation about software, application programming interfaces (APIs), or other technical topics.
  • Trusting team members to value documentation, respect end-users needs, and advocate for the best deliverables for consumers of the documentation.
  • Automating and integrating documentation builds so you and your teams can focus on content.
  • You can block merging of new features if they don’t include documentation, which incentives developers to write about features while they are fresh.

Tools​

As we’ve touched on before, documentation needs to be consistent and centralised. Here are the two tools I think we could use to help with our goal.

Docusaurus​

The first option is Docusaurus. Docusaurus is an Open Source project project based upon React. It was developed by Facebook. It takes markdown files and builds a simple application which renders the content in an appealing manner. It supports translating and versioning.

Pros​

  • Markdown
  • Algolia search
  • JamStack
  • Versioning

Cons​

  • Doesn’t work across multiple repos
  • No feedback mechanism
  • Limited plugins
  • Would require custom pipelines and S3 triggers to redeploy on change

Backstage​

The second option is to use Backstage. Backstage is an Open Source developer portal platform. It was developed by Spotify but it has a much more feature rich ecosystem. It provides the ability to abstract away a lot of the infrastructure, CI/CD, and operational knowledge needed to run an application or product. Also, it can establish the foundation of your developer experience to provide a central hub of information for your company’s services. Its downfall at present is that it does not integrate with Gitlab seamlessly.

Pros​

  • Supports more than just documentation
  • Visualises services, websites and documentation
  • Combines documentation, code and repository overview in a single view

Cons​

  • Scaffolder not yet supported on Gitlab
  • Still in Beta

Complementary Extras​

Mermaid​

Mermaid is a diagramming and charting tool that uses markdown-style text definitions. It automatically generates a great number of different types of charts that can be easily modified & maintained, compared to modifications on Gliffy diagrams.

Pros​

  • Generates a great number of diagrams by code (flow, state, class, entity-relationship, user journeys…)
  • Changes are really quick. E.g. adding a new step in a flow is a matter of seconds.
  • Diagrams would be, then, under version control
  • Great documentation

Cons​

  • Code might be slightly complex to read

Resources​