API Documentation – Now with Listening Ears On

Anne works on the community documentation for OpenStack as a Content Stacker. She is also the author of  Conversation and Community: The Social Web for Documentation.

Do you remember technical manuals stored in several three-ring binders precariously balanced on a shelf, rakishly leaning, and collecting dust? We’re here to change that. All of the documentation served up at docs.rackspace.com/api/ now contain a commenting form at the base of each HTML page. We’re building the documents with a commenting system built in, and we have a team of support staff listening in, waiting for your comments, questions, or kudos.

The commenting system is a global commenting system called Disqus (I think it’s pronounced Discuss). Disqus has been useful for moderation. It immediately sends an email of the comment, with a shortened URL to the page where the comment lives, and it lets me edit all of my own replies. I can choose different systems to show my identity, and if I use a Disqus login, it stores all my comments anywhere that uses the Disqus system. A hidden feature of Disqus is an RSS feed of all comments – see http://rc-api-docs.disqus.com/latest.rss for all the Rackspace Cloud API doc comments, or see http://openstackdocs.disqus.com/latest.rss for all the OpenStack doc comments. I was also impressed with the lack of lock-in – I was able to migrate comments from one set of URLs to another when I moved documents to a /release directory, keeping the comments with the release so they’re relevant for a true point in time.

We’ve been using comments on our technical documentation for OpenStack for a few months now. If I had to categorize the comments, I’d say that people genuinely want to improve the documents or understand the contents better. Those are both great goals – to improve and to learn – and we hope that opening a conversation lets you get closer to those goals. Plus, typo-spotting is a new sport. I challenge you to find the typos in our documents and I know we’ll deliver responsive documentation.

  • Was this article helpful ?
  • Yes   No

9 COMMENTS

  1. Hi Melanie –
    Thanks for asking. I’m a fan of Mindtouch, but in this case, we’re using DocBook to author the API guides. Our build system inserts the Disqus commenting code thanks to the work of talented Rackers, who also did the great CSS styling.

    For OpenStack, we have collaborative authoring on the docs through the openstack-manuals project on Launchpad, which also builds HTML and PDF from DocBook and uses Disqus for comments. It’s sort of wiki-like in that anyone can author docs on OpenStack. The Cloud Files Dev Guide matches the OpenStack Object Storage Dev Guide in many ways, so we get some additional content reuse that way. In many ways, the two doc systems, Rackspace and OpenStack, are benefiting from each other. 🙂

    Anne

  2. I’m curious. Many authors, launchpad, wiki like, yet it finishes up as docbook to get to HTML and PDF? The workflow is of interest Anne… to me at least, perhaps other docbook users?

      • Which implies an RST to docbook conversion Anne? Doesn’t say so but that’s my guess? Elsewhere the argument is always about authors wanting to use Word, techs wanting XML as input. Do you find you can get good structure from RST files?

        It seems that asking non techs to use XML is pointless and no one has come up with an editor that makes it easy.

        • Yes, we have an experimental RST to DocBook conversion tool built in-house very recently. For authoring, the segmentation for OpenStack docs is defined by audience – RST doc written by and for Python devs, DocBook for API documentation.

          You’re accurate in saying that XML is a high barrier to entry for many, but we have techie tech writers here at Rackspace. We also are building “Rackbook” which is an Oxygen plugin to make the authoring experience smooth.

          For OpenStack, we’ll take any format from anyone and as an “acquisition editor” we separate the best contributions out of the slush pile. 🙂 You may appreciate my post “Observations from the Open Help Conference” on my JustWriteClic blog, where I talk about some of the unexpected results working on open source docs. Appreciate the interest!

  3. Great article. I poked over to the comments RSS feed and they sure are coming in with great feedback! Enterprised-based documentation could use a direct visible feedback mechanism like this.

LEAVE A REPLY