d-i manual: content status report
Hi.
As the release of sarge is nearing, I wrote something like a status
report about its install manual at
http://www.debian.cz/~kurem/status.html
[Thanks to Denis Barbier for reading the first draft]
I'd like to wake up developers and convince them to start writing
missing bits of documentation.
Dumping here relevant part from the above url:
The manual text itself
Thanks to Chris Tillman's hard work we now have solid base for
sarge manual written in DocBook XML
(debian-installer/doc/man/en/ directory). I guess about 30% is
still missing and we need some actualization. *If* Joey claims
beta2 will turn into final in e.g. 3 weeks and Aj sets up
another aggressive release date (that's what we, still running
on stable, desire), where will be manual then? And how much time
will be left for translators to catch up? If my memory serves
well, official documentation for cds and www is built only once
(just before the new stable is released).
It is clear, that rewriting parts of documentation again and
again just to reflect the current state of the installer is
quite unproductive. I don't propose this. What I propose, is to
write _now_ about stable parts of d-i which _won't change_ (or
will change in very subtle ways) in the future. [e.g. With clear
conscience I do recommend translators to begin with translating
of the welcome chapter right now, because I'm convinced
everything important is in and won't change].
So we are seeking someone with good knowledge of d-i, hardware
(everybody on debian-boot list qualifies) and with perfect
English language skills (to smuggle in few not-so-tedious
messages (see "installation drama" in
en/preparing/install-overview.xml)).
Yet to write:
=============
en/module/
Describe each installer module (this is why the book is
written)
en/tech-info/
Information on how to customize your own boot floppy,
what needs to be compiled into the kernel. Some info can
be reused from the old manual and from the
debian-installer/doc/docbook/kernel-policy.xml file.
en/appendix/files.xml
In part entitled TBD we need to list more files like it
was done in the old manual.
en/hardware/ en/install-methods en/boot-installer/
If booting from USB stick (or any other new method) will
be in official installer, then we should describe it
there.
Update and proofread:
=====================
While translating written parts I did some proofreading and
corrected various typos, but we need to correct _facts_. (I
haven't worked on anything but i386 machines). Chris did some
work on Apple computers, so those should be fine.
Still there are various small bugs all over the manual (like
mentioning various kernel flavors based on 2.2 kernels). We
should also shift from the old cruft (like mentioning floppies at
the _first_ place, comparing to MS-DOS, or being proud Debian
runs on "new" AMD K6-2).
en/partitioning/
General facts should stay there, but *concrete* steps
from installation should be moved into
en/module/part*.xml. Also update to d-i way of doing
things is needed.
en/boot-new/
Some of this (the bootloader part (up to "The Moment of
Truth"?)) should really go into
en/module/${arch}/*-installer.xml. Next we need to
review second stage install (base-config didn't change
so much, but hey, lets be on the safe side). We should
also check/update references to the menu items.
en/appendix/files.xml
Section "Effects of Verbose and Quiet" is clearly
outdated. Do we have these options in d-i at all?
en/welcome/doc-organization.xml
We need small update regarding slightly changed layout
of the new manual. (Maybe shuffle chapters a bit more
logicaly. Why is partitioning between using-d-i and
base-config?)
--
Miroslav Kure
Reply to: