I’m busy preparing a list of desirables for Web 2.0 APIs. One of them is good documentation, and I came up with this term - “Documentation As Conversation” - to articulate much of what is needed in modern software docs - documentation which belongs to the community of users/end-developers as it does to the people who created the product. The counter-pattern is “Documentation As 1995esque blob of HTML that you apparently haven’t updated since 2004”.

Examples of “Documentation As Conversation”:

  • The official PHP docs allow for comments on every single page. Each page represents a function (strlen() etc), meaning you get a great conversation about the intricacies of every single function, and there *are* plenty of intricacies.
  • The offiicial Scriptaculous wiki is a great description of the ins and outs of the API. Likewise Rails Wiki.
  • Javalobby had an effort to effectively wikify the official Java documentation - it still exists, but only for third-party libraries. See, Sun didn't let it go ahead with the official API and did nothing with the idea themselves. Come on Sun, it's not too late to help your users grok the doc!
  • Through his aptly named Loud Thinking blog as well as the official Rails blog, Rails creator DHH (+others in the latter case) offers an ongoing insight into the evolution of Rails that is at once colourful and extremely useful to the community. Unlike a number of clueless "official" blogs, comments are wide open.
  • Jon Udell uploads a video explaining how his lawnmower is operated. Manufacturers should be building a gallery of videos, images, and docs submitted by users to themselves or other sites.
  • The oldest online form of Documentation As Conversation - mailing lists, usenet, forums. Developers listen and take art in the conversation.
  • Those who practice "Documentation As Conversation" not only write themselves, but they shepherd the community and keep their ear to the ground. That is, they curate wikis; they respond to blog articles by commenting or blogging back; and they make themselves available for inteviews and appearances. </ul> Documentation As Conversation is the way software should be documented in the world of Web 2.0. ("Documentation As Conversation" is a play on "Markets As Conversation", AKA the Cluetrain Manifesto.)