Re: Reducing redundancy
Adam Brown <adam@freestream.com.au> writes:
> Yes I can put some effort into this assuming I have the blessing of the
> Debian community. You might have to explain the due process with regard
> to making changes.
Sure. Get CVS access to the boot-floppies area, look around in the
documentation subdir, and hack away. You can either send results as
patches to the debian-boot@lists.debian.org list, or, if they are
no-brainers, request CVS write access and commit them in CVS directly.
> As I said, I'm looking to start a course here in Melbourne and I've
> allocated resources to do quite a bit of writing notes, I'd rather put
> that into something that can be used by the Debian and Linux communities
> in general than contribute another thread to the tangle.
Well, it's more a question of someone helping with the labor required
to maintain the documentation than another "thread". It's seductive to
write a new document, but not the most valuable contribution for users
or developers.
> For what it's worth I think the Debian documentation is good, at least
> on a par with other Linux documentation, I am sure everyone would agree
> that continuous improvement is however desirable.
Yah.
> > 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.
Well, yes, both would require moving to DocBook, which is probably a
good idea anyhow, but not one I'm able to execute right now.
> > 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.
Well, the solution there is to have an early-on "quick-start" section,
a few pages being all you need to really know.
The really hard thing is dealing with all the different architectures,
really.
> > 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.
I can't see, Josip, how you can plausibly claim that the labor is
actually less if you write a document in isolation, and then merge it
into another document. Have you ever tried doing that? I have --
numerous times. For instance, merging architecture-specific
documentaiton into the main install manual, or even in looking to
merge the installation manual into the Installation HOWTO. The fact
is that it's twice as much work -- it's like writing the documentation
twice.
--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
Reply to: