Re: [gentoo-dev] Concerns about the new install guide

[Sven Vermeulen]

On Wed, Mar 03, 2004 at 11:00:56AM -0800, Alan wrote:
> A few hundred pages later I had a tome to take with me that had pages that
> I discarded or sections crossed out (other architectures) and still had to
> carefully go through and figure out only the essance of what was needed.

I know that printing out the installation document kills of some trees. The
only thing I can say to that is *not* to print out the instructions. 

When someone develops documentation, (s)he has to take into account who's
going to read the documentation. In case of the Installation Instructions,
I'm very confident that 80% of the readers are people new to installing
Gentoo. I therefore decided to write the instructions as verbose as possible,
with lots of examples and (hopefully) correct background information.

Not too much background information, but enough for the reader to understand
what (s)he is doing (instead of just verbatim copying over instructions). If
you want verbatim instructions, use GLIS to install Gentoo - it just runs the
appropriate commands without too much user interaction.

If you want a quick and dirty draft of how the Gentoo installation is
structured, good luck finding a correct one. Every attempt to remove
information from the Installation Instructions will lead to removal of
information. Perhaps you don't need the information, but other people do.

When a user reads documents, (s)he thinks about his own environment.
Everything that doesn't fit there is cruft. But when you write documentation
that is going to be read by everyone, there is no such thing as "cruft". We
therefore decided to make frequent use of internal guiding so that users are
guided through the instructions _they_ need, without having them search for
the next appropriate section. Just follow the instructions and make the
appropriate choices. 

I don't know why some people say that they have to search for the next
section that applies to them - the instructions are written in such a way
that you should not search for those instructions, you just click on the
appropriate choice.

*But* when you print out the documentation, you cannot easily click :) For
this reason all links are named with the title of the section (or subsection)
they are referring to. This allows the user to quickly find the next section
if he is reading from a printed version.

> I'd like to see what one of the other posters mentioned, something
> short, to the point, maybe 2-5 pages long with the steps needed for
> $myfavoritearch to install with examples and commands needed.  Something
> a bit more complete than "chroot" but less complete than what's there
> now.

If you want to write on _and_ maintain one, please do so. But we had this
situation before the Gentoo Handbook was created: several
gentoo-*-install.xml documents of which the gentoo-x86-install.xml document
quickly reached CVS revision 1.200 while the rest struggled at about 1.20 or
1.30. Not because they didn't have errors, but because the x86 installation
document was the most read, had the most bugreports and therefore received
most attention.

I thought that the non-x86 architecture developers would be happy that the
Gentoo Handbook was developed: it allowed for the installation instructions
to be fully up to date with their architecture too without them having to put
too much resources in maintaining their guides. I'm very disappointed that
this isn't the case.

Please remember: writing a document isn't hard nor difficult, but maintaining
one is. Especially in case of an installation document which needs to be
fixed asap as it is too important.

I am going to continuously remove guides if they aren't maintained
sufficiently. One thing I completely dislike about TLDP is that they have
HOWTOs that are seriously outdated. I don't want this to happen with the
Gentoo documentation. I rather have less documents but in a perfect condition
than many documents of which more than 50% is outdated, incomplete or plain
wrong.

*And* I'm also tired of developing ways to present documentation than to
write documentation. The last few months we've had almost everything: XML
changes, XML checking, syntax changes, PDF generation, stylesheet changes,
one-page viewing, ... but hardly any new documents. I therefore decided not
to work on this "metadata" anymore (personally - not GDP-global) but only
write up documents. 

Wkr,
	Sven Vermeulen

-- 
 ^__^   And Larry saw that it was Good.
 (oo)                                      Sven Vermeulen
 (__)   http://www.gentoo.org              Documentation & PR