On Mon, 18 Mar 2013, Stan Hoeppner wrote:
On 3/17/2013 3:50 PM, Timo Sirainen wrote:
It's the best I can do myself. I have no idea how they could be improved in any major way. They say that the software developer himself is the worst possible person to write its documentation, because he can't understand what others find difficult..
I don't know who "they" is. Wietse writes all the Postfix documentation himself. It comes naturally when one performs formal software development, not ad hoc, because documentation precedes coding. I would assume you do ad hoc development like most 20 somethings, coding on the fly when you get an idea, no formal definitions, no flow charting, no pseudo code, etc. Correct? If so this is 99% of the reason the documentation suffers, and this is typical of today's crop of young developers, unfortunately.
For highly technical material the author is the only person qualified to write the docs. Having a 3rd party do it has a prerequisite of a Vulcan mind meld. Otherwise you talk and they type, which is slower than you doing it yourself.
Software needs two types of documentation. It needs overview type documentation that describes what it is. This is for the person who is looking for a product and has no idea if this specific product can meet the need.
Second, it needs reference documentation that provides syntax for commands, config files, and the like. This is for the person who is or will be using the product and needs the details to use it properly for the need.
Somewhere in between is documentation that point the user to the right reference section. Providing detailed documentation of a command is worthless if nothing tells me that that command is what I should use for my need.
The reference documentation may well best be written by the software author who knows exactly what syntax, etc. is needed. It's also relatively (and I emphasize "relatively") easy since it can be done as you go.
But the overview documentation may well best be written by someone who knows nothing about it. The expert writing overview documentation may assume the reader knows things he doesn't. It can make sense to the author but leaves the reader without a clue as to what is being discussed. When the author is someone unfamiliar with the product, he asks questions until it makes sense and there is less tendancy for the documentation to assume knowledge by the reader that is not there.
Overview documentation is a lot tougher to write well and it needs someone with good writing skills (not good programming skills). Particularly in the open-source world where enhancements can come quickly, it can be out of date as soon as it's written.
-- Larry Stone lstone19@stonejongleux.com