Re: Documentation co-ordinator's tasks
On Fri, 26 Jun 1998, Oliver Elphick wrote:
> 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.
>
Just link to the tutorial for now, and I can keep the version up to date
in my home directory until there's some kind of procedure in place to
update the centrally-located version.
> 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.
>
> 3. Make packages of the various manuals, as soon as they contain any
> reasonable amount of material.
>
> 4. Arrange for people to be able to upload material and have it appear
> in the development version.
>
All good things.
> 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 anyone on the Debian machines going to be screwing around with docs
without asking? Are all the permissions needed?
Personally I don't mind if other people want to change the document, as
long as they don't get upset if I edit it or change it back. I can be a
little brutal with red ink because I've been a newspaper editor. (though
I'm not as bad as RMS; his comments are in CVS if you want to see the
ego-bruising he sent me. lots of work left to do.) I would prefer to have
everyone working on a unified document, rather than splitting things up by
chapter, and I've quite freely chopped up Larry Greenfield's stuff and
some things from the web site.
However, for a reference rather than a tutorial, this may not be
appropriate.
> 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.
>
This would be cool. The simplest thing is probably to let authors keep the
HTML/SGML in their home directory, and possibly cron job it to the main
web site once in a while or whatever. I'm not sure exactly how the site
works.
> 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!
>
Maybe we could have a submissions address of some kind.
> 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.
I say keep it simple and just get things running for now. Submissions by
email, authors apply the diffs, edit/cleanup, checkout, build, and upload
it wherever. Obviously this is easily scripted, except for the edit part.
Thanks for volunteering to work on this. After all this talk and with a
real web page I will definitely have to put my money where my mouth is and
get the docs written. It is also very motivating to have the tutorial
where users can actually find it and use it, I find. I've even gotten a
couple of positive comments on what's there so far.
Havoc
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: