Quality Tracking with GitHub for Docs

Home/Publications/CIDM eNews/CIDM eNews 04.18/Quality Tracking with GitHub for Docs

Anne Gentle, Docs|Code (used with permission)

A definitive aspect of a docs-like-code philosophy is attention to quality and accuracy. You want the docs to get better and better. You want to know if the docs are out of date compared to tightly-coupled code. You want people to report issues when they see something that needs fixing. The vision is that more readers mean more testers, and those readers and testers should report problems right there on the page.

What do you do when people say, “The Docs Suck.”?

It’s a pretty simple ask:

  • Tell me which page.
  • Tell me your expectations for that page.
  • Tell me how to fix it.

You can then pre-fill with additional information to help you or other collaborators fix the bug, such as the source file and when it was merged into the repository.

All these concerns can be addressed with a great Issue template. To make an Issue template for a GitHub docs repository, save a file named ISSUE_TEMPLATE in the root directory that contains the information you need in Markdown format. Add headings, links, @-mentions, and task lists to your Issue template.

In OpenStack, we use JavaScript to pre-fill the bug form with the page title, URL, a link to the source file itself, and any tags to add to the logged doc bug. I’m sure you could adopt something similar in your static site generator as well.

Users click here:

Next, users go through a bug reporting workflow with a pre-filled template:

To take it a step further, you can also add a link to edit the source doc file in GitHub’s web editor workflow to have the person fix the bug themselves.

From no reviews to many

In traditional enterprise doc systems, writers can go weeks without getting reviews or input. Even when asking and nagging multiple times, sometimes the documentation systems are so separate from code systems that technical reviews are through

Working in the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though in reality it’s about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click in order to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules really well.

We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close