Functional Approach to Documentation
I have a love-hate relationship with documentation. I'm not the best at remembering to comment my code, but after working in a documentation-free environment for three years, that bad habit is not just broken, but is huddled in the corner crying, begging for the pain to stop, oh God, I'll be good, I promise, just make the bad coders go away. Erm, yeah. But it seems like every time I consult technical docs, I end up frustrated that the documentation doesn't address the issues I have. Examples:
I'm having trouble grasping some very basic concept of what some button *is*. The icon is indecipherable, and the tool tip simply says "juggler". I consult the documentation. The documentation doesn't say what the juggler button is or what it's for, but it goes in-depth into the algorithm used to yark the fleeblejacks when you click the button. Oh good. I'm glad it told me that. Now, what is a fleeblejack, and why might I want to yark it? After spending an hour looking up cross-references, doing google searches, and crying onto the index pages, I believe that yarking is similar to the multiply function, and fleeblejacks are possibly related to spline paths. So, the "juggler" button seems to translate to "darken the outlines". After playing with the button in a test run, it seems to do something like that. One time out of five it does something totally bizzare, and one time out of twenty it throws a fatal error that shuts down the program. I decide that I'm not really any closer to figuring out what the damn button does than I was before, I've wasted several hours working on it, so I go back to using the program the same way I had been before, ignoring the juggler button as more trouble than it's worth.
There's this other button, called "gleem", that I look up in the documentation. The docs are much more helpful here than before, and after reading them, I totally understand what the gleeming is and I get some ideas of how I might want to use it. I open up a test window and start to play. I create a fleeblejack, feeling very clever that I'm using what I learned from my previous failure. I select the fleeblejack and press "gleem". Nothing happens, but the fleeblejack is no longer selected. Huh? I select the fleeblejack, press shift, and hit the gleem button. A new window pops up with a gleemed fleeblejack in it. Great! But... I needed that in the original window. I close the window, and spend twenty minutes trying to gleem a fleeblejack in my main window, with no luck. I go back to the documentation. The documentation says nothing about opening new windows or how to get the damn button to work, it just says that it gleems fleeblejacks and watooris. Yeah, I get that. Do I select it first? Do I need to double-click? Why does holding down shift pop open the new window anyway? Why does my icon change? What is it supposed to do to a watoori? After spending an hour doing some research on the internet, I discover a tutorial on a Czech server, run it through a translator, and discover that I need to click gleem, then create my fleeblejack or watoori, and then press tab, in order to get it to work in the original window. Well, that was counter-intuitive. I'm so thrilled at being able to gleem that I look up how to say "Thank you" in Czech and fire off an email to the author of the tutorial.
Then there's this other button, labeled "bjark". Now, I'm a bjarker from way back. I've been bjarking since I first started working with computers. I can bjark like anything. I even wrote my own little bjarking program for extra credit in my programming class. I totally know what bjarking is and just about every trick to using it. But for some reason, this software doesn't seem to have a counter-bjark feature, which is really helpful if you're going to be doing any advanced bjarking. I consult the documentation. It explains what bjarking is, but I already know that. It has a mini-tutorial on how to bjark and how to use bjarking in a practical application. Great, but what about counter-bjarking? Sure, it's a little more advanced, but you'd think they'd at least mention it? Somewhere? Is there an appendix? Nada. Sure, you talked about the yarking algorithm for fleeblejacks, but you don't discuss counter-bjarking? As a power user, I am offended.
So, in my admittedly ignorant opinion, all documentation should be written with three types of users in mind. Each one requires a different approach to the documentation, all three of which should be addressed in top-quality docs.
Conceptual - This is a beginning user, looking for quick overview type information. What is the button for? What does it do? What are the related functions I should know about before I go clicking things willy-nilly?
Practical - This is the hands-on user. This person needs to see the process outlined and see an example of a practical application of the button in action... A mini-tutorial designed to give the user some experience in using the button.
Technical - This is the power user, either an expert in the field or a programmer. They want nitty-gritty details explaining how the button works, and why it does the things it does, the way it does. But dear gods, don't go into the yarking algorithm until you've covered the conceptual and practical information!
Gods forbid I should ever write software again, but if I do, I'm going to thoroughly document it using this approach.
I'm having trouble grasping some very basic concept of what some button *is*. The icon is indecipherable, and the tool tip simply says "juggler". I consult the documentation. The documentation doesn't say what the juggler button is or what it's for, but it goes in-depth into the algorithm used to yark the fleeblejacks when you click the button. Oh good. I'm glad it told me that. Now, what is a fleeblejack, and why might I want to yark it? After spending an hour looking up cross-references, doing google searches, and crying onto the index pages, I believe that yarking is similar to the multiply function, and fleeblejacks are possibly related to spline paths. So, the "juggler" button seems to translate to "darken the outlines". After playing with the button in a test run, it seems to do something like that. One time out of five it does something totally bizzare, and one time out of twenty it throws a fatal error that shuts down the program. I decide that I'm not really any closer to figuring out what the damn button does than I was before, I've wasted several hours working on it, so I go back to using the program the same way I had been before, ignoring the juggler button as more trouble than it's worth.
There's this other button, called "gleem", that I look up in the documentation. The docs are much more helpful here than before, and after reading them, I totally understand what the gleeming is and I get some ideas of how I might want to use it. I open up a test window and start to play. I create a fleeblejack, feeling very clever that I'm using what I learned from my previous failure. I select the fleeblejack and press "gleem". Nothing happens, but the fleeblejack is no longer selected. Huh? I select the fleeblejack, press shift, and hit the gleem button. A new window pops up with a gleemed fleeblejack in it. Great! But... I needed that in the original window. I close the window, and spend twenty minutes trying to gleem a fleeblejack in my main window, with no luck. I go back to the documentation. The documentation says nothing about opening new windows or how to get the damn button to work, it just says that it gleems fleeblejacks and watooris. Yeah, I get that. Do I select it first? Do I need to double-click? Why does holding down shift pop open the new window anyway? Why does my icon change? What is it supposed to do to a watoori? After spending an hour doing some research on the internet, I discover a tutorial on a Czech server, run it through a translator, and discover that I need to click gleem, then create my fleeblejack or watoori, and then press tab, in order to get it to work in the original window. Well, that was counter-intuitive. I'm so thrilled at being able to gleem that I look up how to say "Thank you" in Czech and fire off an email to the author of the tutorial.
Then there's this other button, labeled "bjark". Now, I'm a bjarker from way back. I've been bjarking since I first started working with computers. I can bjark like anything. I even wrote my own little bjarking program for extra credit in my programming class. I totally know what bjarking is and just about every trick to using it. But for some reason, this software doesn't seem to have a counter-bjark feature, which is really helpful if you're going to be doing any advanced bjarking. I consult the documentation. It explains what bjarking is, but I already know that. It has a mini-tutorial on how to bjark and how to use bjarking in a practical application. Great, but what about counter-bjarking? Sure, it's a little more advanced, but you'd think they'd at least mention it? Somewhere? Is there an appendix? Nada. Sure, you talked about the yarking algorithm for fleeblejacks, but you don't discuss counter-bjarking? As a power user, I am offended.
So, in my admittedly ignorant opinion, all documentation should be written with three types of users in mind. Each one requires a different approach to the documentation, all three of which should be addressed in top-quality docs.
Conceptual - This is a beginning user, looking for quick overview type information. What is the button for? What does it do? What are the related functions I should know about before I go clicking things willy-nilly?
Practical - This is the hands-on user. This person needs to see the process outlined and see an example of a practical application of the button in action... A mini-tutorial designed to give the user some experience in using the button.
Technical - This is the power user, either an expert in the field or a programmer. They want nitty-gritty details explaining how the button works, and why it does the things it does, the way it does. But dear gods, don't go into the yarking algorithm until you've covered the conceptual and practical information!
Gods forbid I should ever write software again, but if I do, I'm going to thoroughly document it using this approach.