Slug: its-in-my-head
Date: 2007-05-11
Title: It’s in my head
layout: post
Continue reading
Slug: structured-docs-v-the-blank-white-sheet
Date: 2007-05-09
Title: Structured Docs v. The Blank White Sheet
layout: post
Ok, hoping I can wrap up this little rant over Buildr’s RDocs. I just left a comment over on Assaf’s post, Patience, Buildr docs coming up, and I liked the way it came out so I wanted to reproduce it here:
I think that part of the problem is that the structured format of inline docs (JavaDoc, RDoc, perldoc, etc) does not lend itself to writing the “human-readable” documentation that really helps users get the heads around the code and into the same space that the developer was in.
IMO this kind of documentation is best written on a blank white sheet - where the developer can practice getting into the user”s headspace first, then bring the user into their space: “This is what I was thinking and this is how to understand and benefit from it”.
Structured docs are great for keeping your code and your documentation together and in sync, but that structure doesn’t lend itself to the free-form prose that (IMHO) makes for a good introduction to a topic (or piece of software). While looking for examples of user-friendly documentation, I stumbled across this guide -
Creating User-friendly Documentation (go figure!) - that captures some
great tips for writing documentation that users will read and learn from:
The basic characteristics of a user-friendly document can be summarised as:
- User focus
- Task orientation
- Ease of use
- Ease of understanding
- Ease of finding information
Most developers (including
Assaf from labnotes) would agree that inline docs are not enough to get a user up to speed on a piece of software. But having put in the effort to provide comprehensive, structured inline docs, it can be tempting to leave it at that - then not get back to it as intended.
Continue reading
Slug: patience
Date: 2007-05-08
Title: Patience
layout: post
Now that’s how it’s supposed too work.
I posted oh… (looks) 1 hour ago about my frustration with Buildr at giving us RDocs instead of documentation, and Assaf responds in Patience, Buildr docs coming up:
>I agree. RDocs are not acceptable documentations.
>RDocs are reference material, information you need after you know what you’re looking for, and just need to quickly find it.
>Except an official Buildr announcement later this week that will include usable documentation. One you can actually learn from. Hopefully, one you’ll enjoy reading from.
I’m looking forward to it, Assaf, and thanks for the response!
Continue reading
Slug: i-hate-rdoc
Date: 2007-05-08
Title: I hate RDoc
layout: post
Continue reading
Slug: using-lawyers
Date: 2007-05-03
Title: Using Lawyers
layout: post
Continue reading
Slug: my-new-desktop
Date: 2007-05-02
Title: My new desktop
layout: post
Continue reading
Slug: jim-roepckes-trying-flock
Date: 2007-05-02
Title: Jim Roepcke’s trying Flock
layout: post
Continue reading
Slug: presentation-making-connections-technology-adoption-in-the-deaf-world
Date: 2007-05-01
Title: “Presentation: Making Connections: Technology Adoption in the Deaf World”
layout: post
Continue reading
Slug: its-in-my-skin
Date: 2007-05-01
Title: It’s in my skin…!
layout: post
This is great… apparently that new Travolta/Allen/Macy movie about men in mid-life-crisis trying to become bikers has a scene where programmer William H. Macy shows off his new tattoo:
Dudley (Macy): “I’m a biker, dude! I got a tat!”
Doug: “It’s an Apple…”
Dudley: “I know. Trademarked. But what are they gonna say? It’s in my skin b**ch!”
Audio
Continue reading
