Documentation as Code

I prefer keeping all of my documentation—in fact, all of my writing—in plain text files, managed by a revision control system (also known as a code repository). In fact, I treat my documentation very similarly to code:

  • Built from plain text files into a final form (executables or libraries for code; HTML, PDF, etc. for documentation).

    • Builds can be automated (built by pushes to the repository), and can deploy to multiple targests (output formats, languages, websites, etc.).

    • Can be built to static HTML pages for the web, which are fast-loading and require minimal processing power on the backend; can even be served directly from S3.

    • You can also automatically build manpages, HTML help (.chm), or any other formats at the same time.

  • Revisions are managed by the same systems (git, hg, svn) used for code.

    • Drafts are managed on branches, similarly to code.

    • Text can be viewed (and contributed to!) on sites such as GitHub.

    • Updates can be viewed and compared using the same systems as code (GitHub,

  • Writers can use any OS, any text editor (programmers usually have favorites, and so do writers).

    • Plain text (UTF-8) ensures the files can be read and updated on any system, any OS, using basic (free, ubiquitous) software. They are not dependent on any particular software for this to be true.

    • Files can be searched through and operated on by the same command-line tools used for code (find, grep, sed, awk, etc.).

    • Writing can be single- or multi-sourced, allowing reuse of content in many different ways.

    • It's easy to pull text from documentation directly into Application and Web UIs (can be built with the code, as well as by a separate process).

This has a number of benefits for documentation and writing:

  • it can be backed up easily, and since text files are small in size (bytes), they can be efficiently stored, edited and viewed online.

Works on any system, using any editor

Code is written in plain-text files

Documentation can use this simple technology just as easily. If you use a light markup format you can

Easy to backup, transfer and edit

Revision control

Publication pipelines

Simple editing