Re: Reducing redundancy
On Fri, Dec 15, 2000 at 03:57:31PM -0500, Adam Di Carlo wrote:
> > > As an example of the existing redundancy in the installation
> > > documentation, from the documentation page I could potentially arrive at
> > > three different installation guides:
> > >
> > > http://www.debian.org/releases/stable/i386/install
> > > http://www.newriders.com/debian/html/noframes/
> > > http://www.debian.org/releases/potato/installguide/
> >
> > Ah, that's a different kind of redundancy than one I thought about :)
> > Basically, the first one is the official manual. The second one is a
> > semi-random book about Debian, and the third is oriented towards newbies,
> > with the screenshots, `loose' language and all.
>
> I have read the 'installguide' (3rd one) and personally had nothing to
> do with it and agree with Mssr Brown that document was unnecessary and
> whatever work the author did for that document could have been better
> spent on the main document (for which I have very little help).
AFAICT the main technical advantages of the newer doc is that it has tables
and pictures. Neither of those can be added to the official installation
manual because DebianDoc SGML doesn't support it.
The main advantages regarding the text itself is that it's shorter and more
to the point, and that it's less official in tone. We can't really have much
of that in the official manual because it has to have more detailed
explanations, cover a range of possible options during the installation, and
it has to sound official because that's what it is.
Admittedly none of these obstacles are extremely hard to overcome, but I
don't see anyone doing it... Adam (B.)?
> > > Another issue is in the development of Debian specific sysadmin and
> > > network manuals. It is a little disconcerting the way so much redundant
> > > Linux documentation is being developed in parallel. Which reference
> > > should a Debian user turn to: the Debian Network Admin guide, the Linux
> > > Network HOWTO, the Linux Network Admin Guide or the myriad of other
> > > contributed guides?
> > >
> > > It would seem to make sense to me that Debian joined forces with the
> > > developers of the Linux NAG and SAG and helped improve those and added
> > > clauses where Debian specific issues arose.
> >
> > Our System and Network administration guides are hardly finished, and they
> > don't look like getting finished soon. I guess we need someone to actually
> > write the docs about that on Debian systems, then it can be decided whether
> > to make it a separate document or a part of the general Linux documents...
>
> I again agree with Adam and disagree with you here, Josip. Trying to
> write the document first, then think about whether to integrate it
> later is silly.
I don't know about you guys, but I'm fairly sure it wouldn't take me more
than a couple of days to merge in 100KB of content within a text twice as
large. But someone's got to write those 100KB of text, and that's what I
wouldn't be able to do in the same time, not a chance.
--
Digital Electronic Being Intended for Assassination and Nullification
Reply to: