Software As She’s Developed

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 […]

[Read more →]

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 […]

[Read more →]