[Typo3-debian] Poorly documentation

[Kim]

Hi All!

I was the one who wrote the email "Poorly documentation" and I think it is time that I made some comments.

First of all - I have been working with Debian a lot of years as an administrator and I am not a newbie. 

Secondly - When you talk about providing better documentation instead of complaining - thats just plain stupid and nonesense! The main reason for a guy to read the documentation in the first place is to understand how a product is working and how to set it up. If he can't understand anything from the documentation then he can't improve it!

Thirdly - When you make some kind of program and decide to write some documentation you must understand what it takes to write documentation to software or hardware. Writting documentation is not like writting a note for granma and it's not like writting a simple book. Documenting something is a subject on it's own which demands quality skills from the writter. If he hasn't got these skills he should not write, instead he should search for help on writting the documentation from someone who is able to do it in a way that suits the "target". Is it a newbie? Is it someone with great experience? And if it is completely impossible to find qualified help  he should atleast provide as many details as possible.

The documentation I complained about was Debian specific and it sucked. It sucked so badly that I couldn't (after a days testing) get the product working. All due to a lack of filling information. Perhaps the dude who wrote that document assumed that people reading it didn't need a detailed explanation or perhaps he just wrote it quickly on the way out of the house. Anyhow - the person in charge of documentation should investigate what is uploaded before putting it there. Meaning a lot of people could waste a lot of time trying really hard understanding something which almost is completely useless. 

I have been working for a really long time with Debian servers and everything we do - we do from scratch.  I am used to reading a lot of different documentation and ofcourse some are better than others. I have myself writtin a lot of documentation over the years.

There mainly excist two kind of documentation.

1. good or atleast ok

2. really stinks

The number two is mainly writting by homemade nerds who do the programming (which is fine by the way), they can program but they can't write!! And trying so is a big mistake sending a lot of users back to whereever they came from making them quit. 

There is a BIG difference in writting something like: 

In order to install the downloaded packet you must use the RPM command together with an option for installing. Running this command will install the packet:

        rpm -i mydownloadedprogram.rpm

And something like (nerdstyle):

Install you packet you just downloaded running a rpm. Afterwords check where its at with a whereis.

Now everybody can se the difference and all the nerds - those thinking they are really skillfull says: perhaps a little experince what make you understand!! And I didn't know completely fools where going to read my text!

Well in that case don't write it! This is not a userfriendly text even for someone who isn't an experienced person. Both in grammatical and technical terms it's actually nonsense and it goes against every textbook ever writtin on "How to write documentation".

Fourthly - why the panics? Just because someone complains about something you do doesn't mean you have to go into "defence" - look objectively at the complaint!! See if perhaps it fits.

I admit that I myself was furious when I wrote the email and ofcourse thats of no benefit, nevertheless I stand on my opinion. And NO I can't provide something better because I didn't get the stuff working! I ended up using a completely different aproach after I wrote the email and it only worked on the "Freesite package".

Documenting software and other stuff is a difficult task but one must be qualified to do it and atleast let people check it and make changes if possible - otherwise he/she shouldn't do it! It's actually better without documentation than documentation that stinks, meaning: leading you on the completely wrong track and making you waste a lot of time trying to figure out what in the world the writter is saying you should do. Rather than figuring out how to get the software to work.

Kim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.netfielders.de/pipermail/typo3-debian/attachments/20040526/088b2d85/attachment.html