API Documentation – Now with Listening Ears On

Filed in Product & Development by Anne Gentle | July 11, 2011 9:48 am

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

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/[5] 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[6] (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[7] for all the Rackspace Cloud API doc comments, or see http://openstackdocs.disqus.com/latest.rss[8] 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.

Source URL: http://www.rackspace.com/blog/api-documentation-now-with-listening-ears-on/

---