Software As She’s Developed

Mahemoff’s Podcast/Blog – Web, Programming, Usability from the Author of ‘Ajax Design Patterns’ (AjaxPatterns.org)

Software As She’s Developed header image 4

Entries Tagged as 'Documentation'

Man pages that read more like legal contracts

November 17th, 2008 · No Comments · SoftwareDev

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

[Read more →]

Tags: ··

Documentation As Conversation

April 20th, 2007 · 1 Comment · SoftwareDev

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 →]

Tags: ····

Documentation Needs Examples (Duh)

September 23rd, 2006 · 4 Comments · SoftwareDev

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 →]

Tags: ····