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.
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.)
Software As She’s Developed » Blog Archive » Did you hear the one about enterprise reuse? // Nov 23, 2007 at 7:20 pm
[...] Support trumps standardisationThe best way IMO to encourage a certain technology or library is the carrot, not the stick. Make people actually want to reuse what you have to offer, rather than forcing them to do so. I am very sceptical about any situation where architects have to act as the reuse police; if the component or service was designed and documented properly and served a genuine need, wouldn’t the developer be drawn towards it? There would be no need to push them into using it. See Web API Patterns and Documentation as Conversation. Online As a rule of thumb, offering a centralised web service is better than offering a reusable code component. The web service can (should) be easier to use and is language-agnostic. Obviously, there are sometimes situations where code components make more sense, especially from a performance perspective. I wouldn’t use an online service to create a polygon every millisecond, for example. Simple and easy to use As with any API, it should be easy to learn and make calls. For this reason, online services should be RESTful, not SOAP or CORBA or whatever MQ if you can help it. [...]