[Typo3-debian] Poorly documentation

[Jack Sparcs]

Kim,
Ya that doc is bad. Forget about it.
How far did you get?



"Kim" <kim at info.dk> wrote in message
news:mailman.284.1085536821.6288.typo3-debian at lists.netfielders.de...
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