I'm writing documentation for frassle. This Thursday, Dave impressed on me the importance of documentation. But as I work, I'm finding something surprising—it's not just for the users.
The documentation comes in the form of tutorials. Each tutorial takes you through the system with some specific goal: gettings started with posting and categories, installing bookmarklets, using the aggregator, link stacking, or building a custom site in frassle publisher. Each step of the tutorial shows in a small top frame while you do what the tutorial says in the lower frame. It goes step by simple step.
I chose the tutorial appraoch because I believe it's easiest to learn by example. It also give me a way to show you how I do it, so I can transmit not only details about how the system works but also my own tips on how I like using it. You could almost call it the blog-style approach to help.
It's not just for the users
The tutorial approach has other upsides. As I write the tutorial, I have to put myself in the mind of a newbie. I have to write without jargon. Therefore, if I write something and it sounds confusing, I have to ask why.
Often, the reason some text is confusing is that I wrote it poorly. But sometimes, the reason it's confusing is that frassle's design is confusing.
Uh oh! Abandon ship! Design fundamentally unsound—bewildered users running amok!
Deep breath. Ahh. Thankfully, it isn't that bad. I'm doing sanity checks and making little improvements. Why? Because, hey, a tutorial is the same thing as a use case!
That's why writing tutorials is as good for me as it will be for you.