‘Documentation as code’ tools to get you started

Treating documentation as code has become an important part of the software development process. Companies are recognizing that the more they can treat documentation like source code, the more effective their documentation, software development and maintenance become. But it’s not only that — the entire ecosystem of teams supporting the software becomes more effective as well.

Becoming proficient in doc-as-code means learning the tools, including tagging languages, site and page generators, and static web hosting solutions. These are the building blocks of doc-as-code.

Let’s look at three essential tools: Markdown, AsciiDoc and GitHub.

Markdown

Markdown is the quickest way to start the doc-as-code journey, as it allows working in plain text files. Markdown is a simple tagging language for adding formatting to plain text documents.

Markdown’s main advantage is its ability to simplify the syntax. For example, it natively supports a table of contents using static page generators.

Several open-source static page generators, static site generators and text editors support Markdown. Here are a few popular ones:

These tools enable converting content to a format that can be published at run time — i.e., HTML. They also support different themes that extend the format capabilities of Markdown.

In addition, many tools that address complex requirements support Markdown. These tools use HTML, CSS and JavaScript for needs such as conditional filtering, content re-use, variables, versioning, authentication and PDFs. Static site generators that support Markdown allow the use of scripting logic and templates such as Liquid, which not only simplifies JavaScript but also makes it easier to perform complex operations. This rich ecosystem of tools helps beginners get started with Markdown, as they provide the framework and syntax for complex formatting. Many of these tools also work well with tools like Jenkins for continuous integration/continuous delivery and auto-publishing.

To learn more about Markdown, check out these open source tutorials:

AsciiDoc

AsciiDoc offers advanced format syntax capabilities to address complex requirements in highly-formatted content (e.g., user manuals, help guides). AsciiDoc provides power and flexibility without requiring the use of HTML; it supports essential syntaxes such as tables, description lists, admonitions (e.g., tips, notes, warnings) and tables of contents. This extra ability can be a double-edged sword, though, as the doc-as-code approach tries to resist complex formatting.

GitHub

GitHub supports static web hosting. Storing docs in a GitHub repository simplifies publishing, as it enables continuous delivery of the content. GitHub automates the site build process, automatically accessing web content (i.e., documentation) from the server when a branch of software is updated. Eliminating manual publish and deploy steps saves effort and improves focus on content.

With GitHub, the entire team shares ownership of the content; anyone can submit a pull request to update the documentation. Teams can discuss edits and changes — before finalizing them — through comment threads that are visible to the entire team.

Takeaways

Doc-as-code makes synchronizing files in your workspace with files in the project repository much easier. It allows you to write on multiple devices, collaborate with people you share the file with and integrate documentation easily into your workflow. The synchronization mechanism can take place in the background, downloading, merging and uploading file modifications. One file can be synced with multiple locations and once you’re happy with it, you can publish it to different hosting platforms such as GitHub, Dropbox and Google Drive.

Doc-as-code is not limited to documentation generated from APIs and code. Marketing content, IP content and other content inside and outside an organization can also benefit.

As we move to an “everything as code” world, documentation has firmly joined the “as code” ranks. Documentation has changed from a sideline activity to a major one empowered by the flexibility, efficiency, ease and collaboration offered by doc-as-code. Now’s the time to hop on the doc-as-code bandwagon for an exciting journey ahead.


AnnuAnnu Singh is a delivery specialist advisor at DXC Technology and is part of the Digital Transformation Center (DTC) Bangalore team. DTCs are physical centers where DXC co-develops business solutions with global clients using design thinking and DevOps to integrate DXC’s next-generation digital services with mission-critical systems. Annu collaborates with the DTC community and DXC Labs to promote emerging technologies and is a proponent of documentation as code at DXC. @Annu_Singh_Tom

 

 

Comments

  1. Giuseppe De Francesco says:

    We have to agree to disagree I suppose. Document revisioning is natively available in MS-Word (and so many other tools), and editing in Word in Teams allows to attach a discussion to the document as well, on top of the document comments, so why should we waste our time writing markup? If a document has to be published on the web we can always convert it to markup, but 90% of our docs are not meant for the web, so… why?

    Like

    • Lucy Sheridan says:

      Funnily enough, I had a similar sentiment when given the option to use Word (a WYSIWYG format) and Word Perfect 5.1 (a more code like experience). I didn’t want to change… I liked how I was doing it at the time. I did change and I did see benefits – in that the features that were available were different. I lost some benefits of using WP 5.1 and gained benefits.

      Switching to doc-as-code is similar – you’ll lose something and you’ll gain something. What you lose is your familiar UI and the stability of your comfort zone. What you’ll gain is content that can be consumed on any device easily as it is no longer constrained by the printed page. You’ll also gain in that you can apply DevOps principles to what you create – automated checks through a pipeline, automated release. You can also get to the point where your content is auto-generated… You also demonstrate that you are moving to a more digital way of working, rather than steady state.

      Microsoft no longer uses Office products to generate their content and haven’t for long time; why would we constrain ourselves to a format that doesn’t scale well and is limited to mostly manual processing.

      Like

    • Markdown as per me is a means to an end. The end being adopting documentation as code, as it brings certain advantages like integrating documentation with the engineers/developers’ environment and their workflow, making them co-owner of the documentation process and giving enhanced search and update capabilities, making maintenance, portability and scalability more efficient. Additionally, it brings governance to the contributors. By no means do I mean to imply Markdown is a panacea — a cure-all-ills approach. The aim is not to add another competing content management system that, as Riona MacNamara @ Google says, ‘adds to fragmentation of documentation’ but to address existing limitations and concerns.

      Several organizations have knowledge management systems, web-based or otherwise these days. With multiple teams spread remotely collaborating on projects, these teams often report they struggle to find the relevant information embedded in documents across multiple systems, or even updated and reliable documents. Also, as organizations move towards open source collaboration, this can be an approach that can address concerns ranging from the eternal dilemma of do I prioritize new features or documentation, to perception stress and connections.

      Like

      • Giuseppe De Francesco says:

        Yes, you are pointing out a problem of organization, dispersion of content (not tool related) or Microsoft using GitHub for all their websites, which I agree it makes sense. But not all our content is aimed at creating a website or at developers. The fact that we create a BandWagon effect, all in or all out is kinda making it worse. DevOps is never about tools but we have the nasty habit of getting stuck in those. We have to put some brain in it and be able to see when Word and Excel on Teams (SharePoint) is the best way to go, and when instead it’s better to use mark-up on GitHub. Trying to impose a tool with a one-size-fits-all mindset will solve one problem by creating a new one… not really a thing I feel I can agree to do.

        Like

  2. Lucy Sheridan says:

    You are correct in that GitHub is just a tool that serves a purpose, and that there are many tools that could be used. The tool is not the start – it is important, but not the reason an organization would shift towards doc-as-code. Where I disagree is that you appear to confuse online doc-as-code content with web sites. Obviously the content is potentially consumed through a browser, so you can argue it is a web site, but the content could be anything – user manuals, policy guidelines, proposals, process content – there is no limit. Microsoft uses doc-as-code for all their user manuals and support content – this is not just a web site. For my team we evolved from Word and SharePoint to doc-as-code and GitHub – not because it was a shiny and new, but because our users were finding the traditional content difficult to consume. Our evolution was not a direct transition, there were steps on the way, but each step added business value – otherwise we would not have taken that journey. The journey is not for everybody, there are valid use cases for SharePoint and Word, but it should be considered, rather than just dismissed. We had many naysayers, even within our team, who now completely agree that the change made sense in hindsight. We should not refuse to change, just because we are not comfortable with it. Be open-minded.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: