Our installation process allows for many possibilities regarding installations. For instance, we can support EVMS, LVM2, RAID, distcc-powered installations, udev /dev management, ...
All those items can be used/configured immediately during installation. This
leads up to four possible documentation layouts:
1. Full installation integrated
This means that the topic itself is integrated in the Gentoo Handbook.
Although this is a possible road, I'd rather not go this way as it will
make the Handbook too large while only few readers are interested in this
particular topic.
It would also make the installation instructions less static so that
translation teams have a hard(er) time keeping the translation in sync.
2. Full installation duplicated
This method copies an entire handbook and changes it to suit the topic
itself. This is the approach that the SELinux Handbook is going at. I
certainly not like this approach as it duplicates efforts and will make
those duplicated guides be less updated than the Gentoo Handbook itself
(I'm not going to propagate changes further than the current handbook) if
not maintained well.
3. Step-by-step installation errata
This method "uses" the current installation instructions but lists the
changed steps. This way users have to follow both guides: in the
errata-guide they will find where they have to stop following the
official instructions, do some topic-specific aspects after which they
return to the official instructions.
This approach is used by the LVM2 Guide.
4. Full explanation
A full explanation guide informs the user about the topic and how it
works. It tells the user more than just commands, but also the background
of the topic and how it can be integrated in a Gentoo system. A user that
reads the document fully should be able to tune the installation to fit
the topic without any further step-by-step instructions.
This approach is used by the udev Guide and distcc Guide (although the
latter contains some bootstrapping information as that is rather
specific).
The question now is, what approach is the best? I'm not in favor of any of
the first two, but the last two are both working fine. I'm personally more
in favor of the latter one (full explanation) as it is not only interesting
for those going to install a system but also those willing to convert one or
even those not using Gentoo.
The reason why I ask this is because I am planning on writing some guides
concerning RAID, SELinux (if there is still need for it), grsec2, ... and I
want to know what results will be achieved with the writing-style.
I rather have 80 users that know the topic well than 100 users that install
it well but hardly have a clue what they did or how it works to it's fullest
potential.
Wkr,
Sven Vermeulen
--
^__^ And Larry saw that it was Good.
(oo) Sven Vermeulen
(__) http://www.gentoo.org Documentation & PR
pgp92QfDUB7ak.pgp
Description: PGP signature
