Man pages that read more like legal contracts

Case in point: I want to use “find” to find files I’ve recently created.

man find (BSD edition):

-ctime n[smhdw] If no units are specified, this primary evaluates to true if the difference between the time of last modification time and the time find was started, rounded up to the next full 24-hour period, is n 24-hour periods.

If units are specified, this primary evaluates to true if the difference between the time of last modification time and the time find was started is exactly n units. Please refer to the -atime primary description for information on supported time units.

Humane documentation FAIL! The precision here is all well and good to include somewhere, but unnecessary for most usages. Please, just tell me what I need to know and Don’t Make Me Think!.

What I wanted to see:

-mtime t

Include only files modified t days ago. You will typically want to specify a +/- sign. e.g. “-ctime +3” for files created 3 or more days ago. To measure in another unit of time, you can append one of the following to t: s for seconds, m for minutes, h for hours, d for days, w for weeks, but note that “-ctime” unfortunately only works if the time is at least one day. For example, “find . -ctime 1d6h” will return files created in the past 30 seconds.

Technical detail: (the legalese stuff goes here. 99% of users will never need it and never read it.)

The improved version focuses on what the typical user needs to know, uses active voice, avoids the cross-reference (it’s documentation, not code, so embrace redundancy!), and most importantly, includes an example. (The man page does include examples at the bottom, but (a) they should be included against each component too; and (b) they still shy away from concrete values: “-newer ttt”!!!)

A lot of these man pages have been around for two decades or more, with minimal changes to my knowledge; I’d love to see someone like Ubuntu sponsor an effort to bring them up to date. Plain English without dumbing down.

Documentation As Conversation

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.)

Documentation Needs Examples (Duh)

I’m constantly amazed at the amount of documentation people are inclined to create without including a single example.

Man pages that devote pages worth of command-line options, flags, grammar, caveats, historical anecdotes, and NOT A SINGLE EXAMPLE.

Textbooks that devote pages to a particular API, then expose it all in one monolithic program.

Countless reference documentation on HTML tags and CSS grammar, and NOT A SINGLE EXAMPLE.

In a world where free videos make it stupidly obvious how to kickstart your lawmowing experience and watching a screencast precedes the creation of “Hello World” in any language you care to adopt, let’s get it straight: An example says a thousand words.