How to Create and Deliver Intelligent Information
By

A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, there were six back-to-back appointments. We waited in the driveway while another couple toured it.

Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. This house was awful. Every single surface was ugly, out-dated, and dated back to circa 1973. There was a giant hole covered in dirt by the front porch. It was likely dug by an animal. But you know what? I loved it. I wanted to restore it to a vibrant family home, taking it back from the rogue porch-dwelling raccoons — or were they dirt-digging armadillos? We may never know.

Let’s look at your code and documentation base as a great house with a good layout and foundational “bones.” You still need that “punch list” to hand to your contractor. When you move towards more documentation like code techniques, make sure you treat your documentation base like a code base, and track defects. Get that “punch list” done. With a code base, you know how much remodeling you need to do. The same mindset can work well for documents. How dated have your documents become? How accurate are the documents compared to the rest of the code base? How can you make the site livable and vibrant again?

Let’s give your readers the chance to do these quality checks for you as easily as possible.
How? By reporting the bug on the page where they found it.

This technique works well when:

  • You have more readers than contributors, and I hope this always happens.
  • Your readers are super busy. Still, they want to create better documents to help others.
  • You want to know how far your documents have “fallen behind” the truth.
  • You want your documents to be more trustworthy by chipping away at a bug backlog.
  • You have a private GitHub report for documentation, but you want to enable public bug reports with the possibility of tracking back to your documentation reports.
Your best bet is to look at any given page on your current docs site.
Is there a way to report a bug publicly, that is, to add to the “punch list?”
  1. The bare minimum starter level is an email address link from every page.
  2. Level up by adding a link to your GitHub source report Issues page so readers can report bugs.
  3. Even better, write a quick bit of code to embed on every output doc page so that the issue is filled with relevant information beforehand.

Here are some resources to get your first punch in that punch list:

  • Using Python Sphinx?
    The OpenStack documents theme has some Javascript that you can re-use to pre-populate an Issue template. In this way, the reporter sends:
    • The page URL
    • The source URL
    • The git SHA of the commit for that version of the page
    • The release version value
  • For more information, refer to: docs.js snippet.
  • Using a private report for documents, but want to track bugs publicly? Use Issues-only Access Permissions.
Would you like to add a bit of code to create Issues for use as comments later on every page?
Free yourself from Disqus comments.

 

Follow me
Latest posts by Anne Gentle (see all)

Like it? Share it! Spread the Word...