# Treating Documentation Like Code
source: https://developer.mastercard.com/blog/treating-documentation-like-code/index.md

Authors: Chris Gooch. Over recent years the phrase "documentation as code" has become well known in the technical writing community, especially among writers specializing in software documentation. Essentially, "docs as code" means creating documentation by utilizing some of the same tools and processes used by software developers, such as: Version control systems like Subversion or Git to enable cross team collaboration and keep track of edits Automated systems to build and deploy content similarly to how Jenkins is used to build and deploy code To some extent this concept is not new. There is a long history of some aspects of documentation being automatically generated from comments in source code. For example: Class reference documentation for Java can be built from Java source code comments using a tool called Javadoc RESTful web APIs can be documented using Swagger (OpenAPI) specifications in .yaml .json files are annotated with descriptions to provide useful reference information However, in recent years there has been an explosion in the use of static site generator tools. These tools take content written in a readable format, such as markdown or AsciiDoc, and generate a set of HTML pages that can be hosted on the Web as a static website. This has given technical authors an alternative approach to tools such as Microsoft Word, or Adobe FrameMaker. By using a simple markup format to create documentation via a text editor, and by using Git or Subversion for version control, it becomes easier for more people to contribute to documentation. At the same time, this still provides tight control over what gets published. Perhaps because many of the tools and processes are familiar to software engineers, this approach has been embraced by many technology companies. Especially those with a need to create large documentation sites for a developer audience. The use of familiar tools means that technical team can easily contribute to the documentation, thereby helping the technical writers - who will still have a role since most engineers are keen to get on with engineering! Mastercard has embraced this approach for publishing content on Mastercard Developers. Previously, all content on Mastercard Developers was stored in a Content Management System (CMS) and edited via a What You See Is What You Get (WYSIWYG) tool running in the browser. This was fine for simple content pages, but frustrating for technical writers creating and maintaining more detailed content. The editor within the CMS was often slow when running via the browser, making writing and editing difficult. There were also limitations on the style of content that could be produced. Rather than continue "bolting on" more content types to the CMS, the Mastercard Developer team embraced the idea of using a new set of tools to allow more flexibility. Several static site generator tools were assessed by the team before the decision was made to use Hugo (see Kenny Chow's post for more details). Hugo enables authors to create content in any text editor using a standard markdown format in (our writing teams mostly use Visual Studio Code), with material stored in Azure Git repos. An Azure pipeline then automatically builds the web content from the markdown source and deploys the live site. The output looks good thanks to the 'theme' we developed, and the Hugo output matches the rest of Mastercard Developers. The writing and editing process works well, so the technical writers are happy. In Practice Content in markdown can be quickly and easily edited offline with no lag Changes can be committed and pushed to Git within the text editor Atom Hugo can be installed and run locally, so we can view a local version of the content straight away in any browser Multiple technical writers can contribute to the content as we operate in Git branches Using Git branches also means we can work on upcoming features on a separate branch without risk of overwriting the latest documentation Rules can be applied on pull requests so the live site cannot be updated without approval from peers Draft branches automatically build branch-specific versions of the content and deploy to our stage environment, so we can share content with other teams for review Once a pull request against master branch is approved, the site then builds and deploys in a few seconds Documentation created through Hugo is much easier to navigate because we can split the material into a larger number of shorter pages with a full table of contents / menu on the left side Easy to see notes/warnings/tips can be added through adding call out boxes Nice looking sequence diagrams from UML can be created using a mermaid plugin (see this post by Paul Bland for more details) Broken links can easily be found when the site builds so they can be fixed before deploying/publishing Summary Since transitioning to the docs as code model, collaboration and quality as well as speed to deployment has increased massively. We can confidently write documentation for new features, while another team member makes corrections or updates to existing content. We don't have to worry that edits may get lost and where conflicts between edits arise as Git gives us the ability to compare and merge changes accurately.