One of those monumental days ........

[Sy Ali]

On 09 Nov 2005 00:21:52 -0500, Tim Writer <tim-s/rLXaiAEBtBDgjK7y7TUQ at public.gmane.org> wrote:

> In general, it's not so much the format that's the problem but the quality
> and coverage of the content. Unfortunately, most developers (myself included)
> prefer writing code to documentation and there are relatively few volunteers
> who write documentation.

I'll go off into a bit of a rant here..

I love writing documentation.. love love love.. I write docs wherever
I go.. I hop onto the wikis of projects I'm mildly curious about and
fiddle around to fix their FAQ or whatever.  I write howtos whenever I
do anything.

The issue for me has always been that I can't answer simple
questions.. like "what is this?" or "how do I use it?" .. I'm mostly
over "where did it install?".  I really despise seeing a wonderfully
powerful program with zero documentation.. and what's there is laden
with such heavy techspeak that it's impossible to understand.

For example.. it would have been helpful if rsync had a "most common
uses" section with examples of commandlines.  This is something that's
missing in basically everything I try.

Using software is:

* Find it
* Read the introduction
* Read the FAQ
* Figure out how to download it
* Download it
* Download it from a different mirror
* Unpack it
* Figure out how to install it
* Figure out where it went
* Figure out how to get to the inline docs
* Give up on understanding the inline docs (man pages, etc)
* Refer to the website, giving up shortly thereafter.
* Google randomly, finding everyone else's variant issues.
* Try random strings, hoping against hope that sensible errors will get spit out
* Google some more, and interpret somebody else's use
* Luck out or give up.

For me, the only reason I can use an application twice is that I leave
*copious* amounts of docs behind me as I go.  I wouldn't be able to
figure out getting EncFS or VMware working a second time if I didn't
make a simple set of instructions.  Heck, I wouldn't remember how to
get a new xmms skin (since the included one is garbage) working if I
didn't write a note for myself.

I'm only just getting into programming (thanks to Ruby / Watir) and
have a history of non-professional interest.  I love writing comments
and docs.. writing code that's clean enough to understand.. etc..

What's most interesting with documentation is the idea of code's
inline comments being automatically turned into navigable
documentation.. so that all the writing can be done in one place. 
Ruby and RDoc do this nicely via a third-party app.


Ok, I feel better now..
--
The Toronto Linux Users Group.      Meetings: http://tlug.ss.org
TLUG requests: Linux topics, No HTML, wrap text below 80 columns
How to UNSUBSCRIBE: http://tlug.ss.org/subscribe.shtml