BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage Articles Always Be Publishing: Continuous Integration & Collaboration in Code Repositories for REST API Docs

Always Be Publishing: Continuous Integration & Collaboration in Code Repositories for REST API Docs

Bookmarks

Key Takeaways

  • API documentation provides a critical path for predicting customer success.
  • Collaborating on documentation close to the code provides better reviews of both the code and the document files, more automation efficiencies, and enables quality tests for documentation specifically.
  • Provide common documentation frameworks, standards, automation, and tools to give teams an efficiency boost.

Writing documentation can be downright boring sometimes, but great documentation is an excellent precursor to increased adoption of an API. Writing excellent documentation is as exacting as the code itself. There are syntax errors and unwanted whitespace that you can introduce. Sometimes your ideas simply stop flowing, but you still need to fill in the blanks to make sure your documentation is complete. With the growth of APIs as products, your documentation is more important than ever in order to create a successful API. API definitions and documentation go together, and while API specifications today are increasingly managed as code in GitHub, the API docs are not. Let’s change this to make the standard to write and manage API documentation, including related web sites, in GitHub and related code repositories.

By writing documentation collaboratively as close to the code and API definitions as possible, you can automate documentation tests, builds, and deployments. Documentation for APIs is often built as a website, so tests such as link checking can happen during a staging build, for example. This approach provides many benefits: tested document builds, continuous publishing, reviews of the documentation content and the code together, multiple outputs including tested code examples, release management for documentation such as early access releases for an API, or incremental changes and additions to a released API, and preventing code from merging unless it has adequate documentation.

Introduction to Documentation Continuous Integration/Continuous Delivery

For REST API documentation, three frameworks provide documentation output in the form of web pages, many of them interactive. These are OpenAPI (Swagger), RESTful API Modeling Language (RAML), and API Blueprint. OpenAPI, previously known as Swagger, is based on JSON, and because YAML is a superset of JSON, you can interchange the source files that describe the API. RAML is a YAML-based language to describe REST APIs. API Blueprint uses Markdown and can also adhere to GitHub Flavored Markdown syntax.

Many programming languages have a documentation framework that integrates well with the code itself. Typically, these are static site generators, such as Jekyll for Ruby, and Sphinx for Python. The source files for the docs are Markdown or reStructured Text (RST). With these static site generators, you can make beautiful documentation sites. In fact, there’s a collection of links to beautiful document web sites on GitHub that includes the Stripe API documentation site and Basho documentation - these are exemplary API sites that get top marks for beauty and utility.

Because these documentation source files and website configuration files can be transformed using scripts, you can continuously build the documentation with the same build jobs as the code. Jekyll sites are deployed by copying flat files from a static directory, so you can store a script to build the site in the code repo with other build files. You can also have a simple link checker to test for any broken links before deploying the site. The HTMLProofer library is a Ruby library written to do just that.

The deployment mechanism provided by GitHub is called GitHub Pages. You have some options for triggering a documentation web site deployment. You can automate builds from a gh-pages branch, from the master branch, or always deploy docs from a /docs directory on the master branch. Your GitHub repo has these options on the Settings page. While you can deploy to a custom domain name, one limitation of GitHub Pages currently is that you cannot serve directly through HTTPS, but as a free service it’s a good starting point. For production web sites, you can deploy from GitHub to a cloud server or VPS that has the security requirements you need. More or less, you are creating your own hosted web site. GitHub Enterprise, an internal deployment of GitHub for on-premise use, offers similar hosted site capabilities.

Why treat documentation like code?

Writing with developers and for developers works well when the deliverables help developers. API documentation tasks provide a great example for why and when to treat documentation like code. Especially at critical design points when designing an API or adding features to an API, developers can contribute to the documentation when it is just like code contributions. Sending emails back-and-forth does not help cement the documentation and make decisions at those critical points.

You gain speed and accuracy when automating reference information, for example, and gain contributions, quality, and empathy by writing collaboratively in a social coding system like GitHub, Bitbucket, or GitLab. Also, one of the biggest success indicators for an API is the accuracy and helpfulness of the documentation. Here are some specific benefits when your teams treat API documentation like code, explored more thoroughly below:

  • Collaboration efficiency
  • Contribution gains
  • Bug tracking for documentation
  • Open reviews for documentation and code together
  • Deployments and releases for documentation web sites
  • Tests and builds for documentation accuracy and web site deployment

Collaboration efficiency

Having developers and technical writers write collaboratively provides both roles with valuable information. Developers want to write for an audience that resembles themselves, and can provide empathy for the reader. Writers have a special knack for organizing information, writing well, and revealing concepts and reference information in the proper order. Collaborating together in the same repository increases opportunities for both teaching and learning.

Contribution gains

When you don’t "throw writing over the wall" to a technical writing team, you can broaden the number of contributors, even if the API itself is not a public one with public documentation. Or, you can enable more contributions from the end-users themselves by providing open source documentation repositories in version control systems like GitHub or Bitbucket. Any interested developers, including customers, can subscribe to notifications on pull requests when the documentation is in the same repository as the code.

Bug tracking for documentation errors

For higher-quality documentation, provide a way to report documentation bugs directly on the output page. As Linus’s Law states, "given enough eyeballs, all bugs are shallow". By providing those eyeballs a place to report the bug, you give more code-like quality tracking to the documentation. Plus, with metrics in place through issue tracking, you can measure the quality of the documentation and ensure resources are in place when needed to squash those bugs.

Open reviews for documentation and code together

When reviewing documentation files that are included with code, reviewers can block a change to the code when the documentation is insufficient. This review guidance provides the team with the power to make the documentation high quality, even when they have to be synchronized with fast-moving code.

Having the documentation source files in an open system like GitHub enables the content to have open contribution, similar to open source code. In OpenStack, a large collection of open source cloud projects, the documentation contribution process is identical to the code contribution process. Both writers and developers have the same collaboration tools and background knowledge when they approach a documentation-only repository, a code-only repository. or a repository that contains both documentation and code.

You may also consider using GitHub Enterprise for internal API documentation when your API definitions require a level of gate keeping or careful fencing. Your teams still get the collaborative benefits internally, without opening your documentation and code to the world.

Deployments and releases

When treating documentation like code, realize you are separating builds from deployments. This way, you can have reviews on early drafts of documentation and it does not become contractual until the documentation build is deployed and released to a website, for example. Or, you can choose to release some documents continuously to keep up with the code. For example, you may choose to write narrative documentation and tutorials that release continuously with every landed patch set. But for contractual documentation like an OpenAPI specification, you can only deploy new documentation when the API is considered released at a specific version.

Tests and builds for documentation

By having a matched staging build for reviews and a production build for delivery to readers, you can be confident your review of built documentation meets user needs. Refer to the examples in the section below.

Example tests for docs

You can test document source files for quality and whether they build. You could also check for spelling or grammar, but typically human reviewers can also do this. The point of testing documentation is to take that review burden off of human reviewers and let the automation save time so that more document files can be written, published, and released.

Link check

With many static site generators, there are libraries specifically for checking all the links in a site. For example, when checking links on a Jekyll website like docslikecode.com, the Travis CI job is simple:

#!/usr/bin/env bash
set -e # halt script on error
bundle exec jekyll build
bundle exec htmlproofer ./_site

With this type of test in place, human reviewers don’t have to take the time to click on every link in a new patch. If an external link should be updated, the results of this test let you know. If an internal link breaks due to the patch itself, the contributor can fix it before a human even needs to review the patch.

JSON format

With REST API docs, the requests and responses are often JSON files and are valuable to readers in comparing their own environment to the documentation. It’s critical that the examples are formatted correctly in case a reader needs to copy and paste the request. In OpenStack, we have a set of common documentation tools that contain a JSON tester and formatter. By running this test on incoming patches to the document files, reviewers can determine if the included JSON files are formatted correctly. Plus, it makes the patch creation easier for a contributor when they can run a simple command locally to ensure the JSON format is correct.

Validated requests and responses

An advanced documentation test can provide checks for the example requests and responses included in the documentation. When reviewing document files in the same way as you would review code files, accuracy is often the highest value. So, by testing examples against a working API endpoint, you can show that the examples will work in the real world as well. This type of validation provides trusted documentation examples that work every time, because they won’t be published unless they pass a validation test.

Build check

Automating the documentation tests frees up reviewer time because they do not have to build the docs themselves to review the output. In addition, you can test the build for broken links or improperly-formatted JSON files, for example. It’s helpful to review both source documentation and output documentation for any oddities or problems.

Conclusion

Working on documentation collaboratively in the same repositories as the code base provides the opportunity to better serve customers, whether they are internal or external to your organization. By treating your API docs like code, you can find automation opportunities, gain efficiencies, speed up documentation builds, build trusted examples in your documents, and enable more reviewers and contributors.

About the Author

Anne Gentle works as a technical product manager at Cisco, supporting the Metacloud product based on OpenStack. She uses open-source techniques for API design, documentation, dev ops, and developer support. OpenStack provides open-source cloud computing software through collaboration among more than 30 projects written in Python across hundreds of Git repositories. Collectively, the projects provide over 25 REST API services with thousands of API calls. She wrote the book Docs Like Code to share these tested tools and techniques with all who want to provide helpful, accurate technical information to the world. Read more here.

Rate this Article

Adoption
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

BT