Re: Documentation co-ordinator's tasks
Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl> writes:
> First of all, I support you as the DDP co-ordinator.
Oliver, I second you as well. Not that there's really a voting issue
about it..
> So, I'm orphaning all the manuals with my name as maintainer.
Ardo, yes a good idea.
> This
> includes the meta manual, user's manual, the sysadmin manual, the
> netadmin manual, the dictionary, and the book suggestions list. The
> user's manual should be renamed to reference guide.
Geeze I'm almost tempted to take that and outline it and then orphan
it. That would be slash-n-burn though wouldn't it.
> For the book
> suggestions list and the dictionary Christian had the idea of making
> them web-based in the sense that anybody could submit new entries for
> them, provide updates of existing entries, etc.
The Faq-o-matic is like that (although I couldn't help feeling that it
still needs agressive maintenance, i.e., taking good questions from
debian-user and populating the faq-o-matic). I think that's a good
idea, but don't fool yourself into thinking that a faq-o-matic
arrangement means it's maintenance-free.
> We already talked about some design issues, but it got never beyond
> that point. I hope all of them get suitable parents. :-)
We can hope.
> "Oliver Elphick" <olly@lfix.co.uk> writes:
> > Since I have volunteered to take over the job of co-ordinator that has been
> > made vacant by Christian Schwarz's departure, I had better explain what I
> > think needs doing, so that you can all decide if you want me to do it.
> >
> > 1. Move the DDP webpages onto a Debian machine (www.debian.org?); ask
> > Christian to alter the page at his site to point to the new location.
> > Add Havoc's Debian Tutorial to the pages.
Yes, and mark as orphaned what is orphaned.
> > 2. Move the documentation source onto a Debian machine. Get from Ardo
> > or have people resubmit any contributions they have already made
> > and make sure that they are published.
You should tolerate heterogeny. I.e., robert wants to keep source on
his own machine, and I guess manually update you; eventually he will
move to CVS.
I think you should gently encourage *everyone* to use cvs.debian.org
but not make it a requirement.
> > 3. Make packages of the various manuals, as soon as they contain any
> > reasonable amount of material.
I think this is kinda a big job, no? Do you really want to do this?
I think you could still be quite useful w/o being the actual packager
of the various manuals. I'm worried you'll get too bogged down.
> > 4. Arrange for people to be able to upload material and have it appear
> > in the development version.
Development version of what?
> > I'm not sure of the merits of using cvs to do this, because I think that
> > only the original author and the editor should be changing text. Is it
> > possible to arrange cvs with limited permissions? [Each chapter owned by
> > its author, and in the documentation group; only the editors are group
> > members; all document sources have 664 permissions.]
Certainly.
There's another reason cvs is useful: contributors can be assured of
patching off the *very latest* version. So it's revision control and
software distribution in that sense.
> > Ideally there
> > should be some kind of server that accepts submissions from authors,
> > incorporates them and runs a make of the HTML documentation, and (on
> > success) copies the HTML and SGML onto the website.
Yes, it looks like James will help you there.
> > Any material submitted should either appear on the website or be rejected
> > within a week. Reasons for rejection would mainly be that the SGML fails
> > to generate output; other circumstances are conceivable but would (I hope)
> > never arise!
This reminds me of the linux patch page at
http://samba.anu.edu.au/linux-patches/ (isn't Jitterbug a .deb yet?).
I think it's outside your scope as document coordinator to enforce
this for the documents themselves, although you might provide some
sort of infrastructure for doc maintainers to use for kicks. Don't
get too ambitious here, though, let's keep it simple.
> > Any errors in content should become apparent if submissions are published.
> > If an author fails to correct an error quickly, I would expect to do it
> > myself, to avoid misleading readers. If any dispute arises, it would
> > ultimately go to the Technical Committee.
Sounds good.
Maybe it's my confusion, but I think you need a quick statement of the
*scope* of your duties.
--
.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: