Support: 1-800-961-4454
1-800-961-2888

API Documentation – Now with Listening Ears On

9

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.

About the Author

This is a post written and contributed by Anne Gentle.

Anne Gentle is the fanatical technical writer and community documentation coordinator at Rackspace for OpenStack. Through collaboration and continuous integration, running the documentation project like a code project, Anne has helped the community produce and maintain installation and administration manuals, how-tos, API information, and reference documentation since September 2010.


More
  • http://prosekiln.com Melanie

    That’s very interesting, Anne. Thanks for sharing.

    What platform do you use for the documentation overall? Mindtouch?

  • http://justwriteclick.com Anne Gentle

    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

    • http://prosekiln.com Melanie

      Very cool! Thanks for sharing.

  • http://www.dpawson.co.uk Dave P

    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?

    • http://rackspace.com/cloud Anne Gentle

      Hi Dave -

      Sure, I can tell you more, and I’ve written it all up on the OpenStack wiki at http://wiki.openstack.org/Documentation/HowTo. I’m always interested in collaborative authoring platforms so I appreciate the curiousity! :) To be clear, the OpenStack documentation is open to multiple authors, the Rackspace documentation is collaborated on with Rackers.

      Thanks,
      Anne

      • http://www.dpawson.co.uk Dave P

        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.

        • http://rackspace.com/cloud Anne Gentle

          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!

  • http://contentevangelists.wordpress.com/ Sandra Durham

    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.

    • http://rackspace.com/cloud Anne Gentle

      Thanks, Sandra! Yes, we’re super pleased with the conversations going on. I know our docs will improve thanks to customer input.

Racker Powered
©2014 Rackspace, US Inc.