Documents as code

Collaborative mode: “All hands on board”

Developers on daily basis have to share the same resources, we try to minimize conflict and avoid working on the same behavior exactly at the same time. Even if we cannot synchronize correctly all the time and avoid conflict, we still have the opportunity and –thank the stars! the tools to accomplish it.

Having the opportunity to “collaborate” on the same file at the same time without overwriting other collaborators efforts, increase productivity –big words! I know!

Traceability: “Who on earth dared to …​?”

Being able to pinpoint an specific instant where content was added or removedis invaluable.
If the author of those changes is also kind enough to provide a context or reference of why the change was introduced it’s even better. A clearer picture is presented to the reader effortless.

Answering questions like:

  • What changes have been introduced in this document in the last week, day, hour, during this period?
  • How many changes were introduced by an specific author?
  • How frequently is this file being modified?
  • How many people collaborated on this content?

It’s simple!

Flexibility: “How do you need it today?”

Having a single source of truth that can be “render”“transform” into different formats is important. Now imagine you can have blocks of content being displayed or hidden based on conditions, that’s amazing!
No longer you have to worry, endlessly copying & pasting from one file to another.
Not having to keep synchronized different formats of the same file.

ONE file, just one. That’s it!

Exploration: “I know I saw it somewhere”

Using simple text documents make searching patterns a breeze. Simple tools can calculate the content’s difference between two documents or even within different versions of the same document easily.

We can run validation checks using scripts to check for broken links, missing images, improper terms/styles, formatting errors.


What has worked for me in the past (and several companies like: Redhat, Github, Atlassian) is Asciidoctor with git.
That’s it! That combination is powerful enough to start a revolution!