Man Pages, HOWTOs, and Tutorials
Posted by notKlaatu , 08 August 2008 · 51 views
Documentation, for me, is a really important issue. You can see how as computer programmes become more complex and specialized to certain markets, how vendors are intentionally not documenting the application, so that third party vendors are then able to sell the "missing manuals" for an additional fee.There's an argument that could be made that technically the software company does not have an obligation to teach people how to use the program; instead theirs is to document what exactly it does, rather than how it is done. I do not agree with this for two reasons; firstly, because often people have paid too much for the software in the first place and deserve to learn how to use it for that price, and secondly because documenting how to use the application really is part of documenting what the application does, since the Results is the reason for the software's existence (that is to say, no one buys a software because it is ABLE to do something but in order to get something done BY it -- it's why we have Save, Print, and Export buttons).Many forms of documentation are guilty of this kind of thing, not just the manuals of proprietary software applications. Some *nix man pages are horribly written, without any clear indication of what the program actually does, giving instead a list of all the obscure options people can use on an application they know nothing about. Online tutorials sometimes do the same thing, assuming that the reader is pretty much exactly where the writer is, using jargon and shortcuts that would bring a noob following along to a grinding halt.I do the same thing in some of my tutorials sometimes. I try not to, but it's an easy trap to fall into.And there's the question of how far back must the author of a manual or tutorial regress to ensure that the reader is with them. Do I have to start simply how to launch the application? or must I tell the person how to turn their computer on, or maybe give them buying advice first, and so on and so on to further levels of absurdity.Realistically, a few steps of regression is all it takes, depending on what kind of tutorial is being written. If it's a tutorial on advanced color correction in Blender, then I must assume that the user has progressed in Blender enough to have edited some images together. I should NOT assume that they have ever used Blender plugins or the node compositing window.Just imagine opening a man page that read a little bit something like this.......(this is not a real man page but an example I made up, inspired by many real ones I have been subjecteded to)
Gamma and Luma Curve ToolAdjusts the gamma and luma of an imagecurve [in file] ... [options] ... [out file]-k adjusts the knee-s adjusts the shoulder-i use IRE values only--cont (contrast) is the multiplier for the value and expands the signal the center. If contrast is set to 0, there is no effect. When contrast is 256 all values are multiplied by 2 (twice as bright). If the contrast is 512 all values are multiplied by 3. If cont = k*256 for some integer k (and zero gain) then Y becomes Y + k*(Y-128) (idem for the chroma). Although it is possible, it doesn't make sense to apply this setting to the luma of the signal.OK while I'll admit that that makes a fair mount of sense to me, i personally doubt someone new to the process will get much information from that. What most users who really want to use it would hae to do is to map out a study plan for themselves with notes "find out what gamma is, find out what luma is, what's a knee and shoulder, what is IRE and how do I use it" - to say nothing of the question of what kind of values are we looking for here? percentages of IRE? the exact IRE you are aiming for? and wtf is all that stuff about contrast??Yes, the above man page documents accurately what the tool does and i can absolutely see it being a good rereference page (maybe man pages should be renamed "ref pages"?) for people who already know how to use the tool, but as far as proper documentation goes, it's not helpful at all.Good documentation -- for a good example, see the Image Magick software package. It's a CLI tool for image adjustment an even generation. That in itself is bizarre enough but to make matters worse there are 5 or 6 little apps within the Image Magick umbrella. Yet the man pages are informative and clear, and EXTRA documentation for people very unfamiliar with the program, is available as local .html files that can be easily viewed in any browser. It's the kind of documentation that you would, these days, usually have to pay $30 dollars for, or if you were crazy and bought the version of the book with the "Free Software Inside!!!!!" cd tucked in the back, you'd pay $50.Someone is obviously using these tools. So someone knows how to use them. And one of those people, who uses the software and knows it, is able to write proper documentation -- even a poorly written, grammatially incorrect document is a good start! To use the software we are working so hard to create, to say nothing of promoting its prolifieration, we MUST document and we must document WELL.Think of this -- given the choice between a well-documented proprietary software and a poorly documented free software, people will choose the proprietary. They may have to steal the proprietary software via a warez site, and they may have to pay $30 for the manual at their local book store, but at least they can learn it. If there is no such recourse for free software, then you can't possibly expect people to invest their time in trying to figure it out.Super Positive Winning Examples from our Free Software effort:Inkscape - between its own documentation and the absurdly prolific http://screencasters.heathenx.org tutorial site, inkscape has a lock down on howtos. Besides that, its a rocking app. Eat your heart out, Adobe.Blender - most of this is quite well documented and many tutorials are available on it. It is a very pro-level app, but I dont see how there is any more documentation on it than, say, Shake or Motion. There is a bit more on Final Cut by comparison, but Blender is still emerging as a video editing solution.GIMP - lots of tutorials, well documented app...but you know that when you are in the bookstore and you see a GIMP instructional book on teh same shelf as the Photoshop Classroom-in-a-Book series, that the GIMP has definitely arrived.Image Magick - very good, and logically laid out, documentation for new and experienced users alike.and so on and so on. I'm sure there area others but these are the ones I have most experience with.The point is, long live proper documentation! Read it, write it, correct it, contribute to it, make it easily accessible and tailor it to different user level needs. It's important!