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: Set up a private server to host your document repository containing DITA, Markdown, or RST files. Install Git of your choice. Configure the SSH keys that writers could use for authentication. Configure Git hooks for common checks. 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. Connect to the Git repository from your local machine through the configured SSH keys. Clone the repository on your local machine. Create a working local branch from the main or release branch (as configured). Update the content. Create a pull request to merge your updates to the remote branch. Add reviewers for feedback. 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 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. Bitbucket 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 or . 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. Bamboo Jenkins 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 and . The idea is easy maintenance and reduced operating cost. So, would you treat ? Write the Docs RedHat docs as code Previously published at https://medium.com/@mrsauravs/doc-as-code-managing-content-is-easy-when-its-distributed-2ad6370e8dd8

ATLASSIAN

How Nutanix VM Works

Read My Stories

Too Long; Didn't Read

Make resilience your competitive advantage

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

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

How Nutanix VM Works

Advanced CI/CD for Android projects using Bitbucket and Bitrise

Announcing GitPitch Pro

Libraries.io February Progress Update

Deploy a React App to Heroku with Bitbucket pipelines

How Nutanix VM Works

Advanced CI/CD for Android projects using Bitbucket and Bitrise

Announcing GitPitch Pro

Libraries.io February Progress Update

Deploy a React App to Heroku with Bitbucket pipelines

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps