Docs-as-Code: Managing Content is Easy When it’s Distributed

Few months back, I got a call from GitLab for a technical writer position.
One of the question was about treating document as a code and what’s my
view on that. The question was about treating document as part of a
continuous integration and continuous deployment system. That question
came at the time when I wasn’t treating docs as code and ironically, I now have a perspective.

In the documentation world, most organizations prefer a full-fledged
content management system to manage a large document set. This isolated approach has its own benefits but when it comes to collaboration, its value diminishes further. Linus Torvalds had created Git for programmers to version-control the code. Documentation is no different, if you are ready to treat it as a code. The reason why most organizations are
moving to a concept known as docs-as-code.

What is Git?

Git is a distributed version-control system to track changes in the source
code implying that the source can be mirrored or distributed to a local
machine. That being said, the source can be anything. It could be your
application, website, or documentation source. There are many Git
flavors available today in the market. The most popular ones are Github,
GitLab, and Bitbucket.

Github is suitable for open-source projects as the repositories are generally public. GitLab offers free private repositories making it suitable for organizational need. Atlassian owned Bitbucket is a solution that is
adopted by most organizations. The reason being that it could be tightly
coupled with JIRA. For more information, see Atlassian feature comparison.

Git Documentation Repository

Irrespective of the choice of your Git, you can maintain a central documentation repository that can be cloned, used, updated, and managed.

The ideal approach would be to host your documentation repository on a
private server separately and install the choice of your Git on top of
it to manage. This approach is suitable when you want your document
server to host the dynamic content.

In technical writing, there’s always a clash between people who want to
write in Markdown and people who prefer DITA XML. However, there are few differences that needs to be understood first. DITA XML is modular and has many advantages over Markdown. The content re-usability and
localization becomes easy with DITA XML. Markdown is an easy to use
markup language that renders HTML output. Markdown is natively supported in Github and Jekyll. But you need to forget about content re-usability and localization support.

Then there are other languages such as reStructuredText (RST) that offers
many great features. You can read more about the content re-usability
with RST here.

So, it’s up to you to go for the language of your choice. I prefer DITA XML
when there’s a need for localization and prefer Markdown when creating a
static quick start guide.

Setting up a Git Documentation Repository

To set up a Git repository on a dedicated document server, follow these steps:

1. Set up a private server to host your document repository containing DITA, Markdown, or RST files.
2. Install Git of your choice.
3. Configure the SSH keys that writers could use for authentication.
4. Configure Git hooks for common checks.
5. Set up a publishing branch such as main or release.

Now, you can distribute your repositories among writers. Writer would have to follow all the basic principles of Git.

1. Connect to the Git repository from your local machine through the configured SSH keys.
2. Clone the repository on your local machine.
3. Create a working local branch from the main or release branch (as configured).
4. Update the content.
5. Create a pull request to merge your updates to the remote branch.
6. Add reviewers for feedback.
7. Upon approval, merge or integrate your changes to the remote branch.

Addressing the Review Process

Reviews are the most important part of the documentation life-cycle. With Git, you can integrate the review process and remove the need of extra tools.

You can share the same page for the feedback in your Pull (Merge) request
and add reviewers. You can view a sample code review from the Bitbucket
page. The reviewers are able to provide their feedback on the Pull
request itself and depending on your edits, you can choose to merge that
Pull request.

Documentation Builds

The documentation build can have multiple output formats. Most
organizations are happy to have an online help (HTML) along with a PDF
copy.

To achieve this, you need to include plugins to generate outputs. You can
customize an existing plugin or create a new plugin that renders
multiple outputs. Now, the question is where to add this plugin. If you
are on DITA XML and inclined to use DITA oXygen XML Editor, you might
want to look at this page.

Similar to the development builds, you can choose a build server such as Bamboo or Jenkins. You need to add your plugin to the build agents on the build server of your choice. Most likely, your development team will have a build server and you just need to leverage that and designate a documentation build agent.

Localization

If your content is part of localization, you can tackle it easily through
any version control system such as Git. When you merge your updates in a
branch, you can keep that branch for localization. At the end of each
release, you can cut your release specific branch and send it for
localization.

If you have in-house localization team and they use a specific tool such
as SDL Trados Studio or Passolo, using Git to send files would be a bit
difficult. In this case, you need to bundle your translation ready
branch and then send it over to the localization team. For more
information, see Git Bundling.

Content Management System Vs Doc-as-Code Ecosystem

It’s a matter of choice whether an organization would want to be part of an
ecosystem or remain isolated on a separate content management system.
Most organizations have migrated to adopt ecosystems where the
development, testing, and documentation environment can be treated
together.

For example, your development team might already have a file in their code repository containing user-interface labels. With Git ecosystem, you can leverage that file, create a writable copy using variables (of course,
through DITA XML), and reuse the labels throughout your document. You
would need a content key reference to achieve that. The biggest
advantage is that if your development team wants to change a label, it
would reflect in your document as well.

There have been platforms that discussed Docs-as-Code extensively such as Write the Docs and RedHat. The idea is easy maintenance and reduced operating cost. So, would you treat docs as code?

Previously published at https://medium.com/@mrsauravs/doc-as-code-managing-content-is-easy-when-its-distributed-2ad6370e8dd8