I'm wikied out

by Francois Joseph de Kermadec

In my early days, I have done a bit of development work. First it was Hyper Card (my young years), then it was AppleScript studio. My last accomplishment was a complete Customer Relationship Management System developed in ASS (I know, I know), tying in to FileMaker, CUPS, Mail, Excel, HTML Tidy, Python and more. Now, before you laugh, I'm acutely aware that writing an application in AppleScript studio does not have the glory of, say, writing a Cocoa bundle from scratch and linking it to cool technologies like Spotlight but, as with any large-scale project, it gave me a good hand on XCode, development procedures, interface design, etc…

Part of my development work was to write the accompanying documentation for the people who would use the system once the applications would be ready. This was no easy task: sure, my applications were straightforward, with as few options as possible, were doing as much of self configuring as possible but they would be used by interns, who would stay in the office for a couple months, some with absolutely no knowledge of Mac OS X, let alone the accompanying technologies. Then, there was the question of developer documentation, what I was writing for my boss so that he could tweak and recompile the code whenever something needed to be changed — we had chosen to hardcode many options instead of using preferences so as to be sure that any version of the application could only be used in a specific context on which he would decide.

This meant that solid documentation was needed, required even for the system to be used. I spent my time developing making notes, asking for feedback, stuffing my interface with tooltips. Then, I delved into the Apple Developer Documentation about writing help files and wrote as complete an online help as I could come up with. Finally, I wrote two printed booklets: one "Quick Start Guide" and a "Developer Manual" so that nobody, no matter how they were going about the application (carefully planning its integration in their workflow or avidly jumping on it) would be left in the dark.

This took time, about a month. But we had discussed it with my boss and he wanted it that way. I was working on my free time to get it done, saturdays and sundays, mornings and evenings — no, nobody asked me to, I just wanted to do my job well. The result? Anybody with a brain and a few minutes on their hands could, without any exterior help whatsoever walk up to a computer, install the application and get to use it.

Today, I am fed up with the number of applications or projects that don't have documentation or help or anything. Most of them have a couple tooltips and a Wiki or a Forum. That is not enough! No application is clear enough to be used from the start. Even Simple Text on System 7 used to come with a manual. Even Stickies does!

Wikis and Forums are awesome. They allow the community to improve the documentation, build upon it, provide feedback to the developer. But they cannot replace the documentation. By definition, a Wiki is written by someone who feels comfortable enough with the application to need "tips", forums require long searches to extract information: none of these wonderful concepts can replace linear, logically organized documentation.

Yesterday, I have opened an account at a host for someone and was asked to read the forums and wiki for help. Then, I downloaded an application I wanted to test and was, again, referred to the wiki for assistance. Finally, I got a call from a customer for help with a CMS they want to install on their site and that, you guessed it, only comes with a wiki. I'm wikied out! I love wikis, I love forums but, much like chocolate éclairs can become sickening if abused, I can't see another wiki — at least not when it's the first thing you see mentioned in a Read Me file.

We at Antonia, my little operation in Paris, have a tradition: whenever we work with an Open Source project we like but think could use help with the documentation, we try to give a hand, suggest improvements, translate things (in French or English). We take time to help the community and write something that can benefit users at large. Why? Not because we want to "cash in" on the Open Source movement (we don't put our name in the documentation we write for projects) but because we are too often confronted with the need to understand something well and fast, and know that, paradoxically, it is getting increasingly difficult in the collaborative world of today.