Just a few comments, I'm way overloaded for the time being and cannot commit to do major editing. On Tue, Jan 28, 2003 at 12:29:58PM -0600, Adam DiCarlo wrote: > > First discussion point before going to the step (1) is narrow the scope. > > Let's focus on Chapter 2 and Chapter 3. Can we agree? > > Um, why start there? Right in 1.1, Scope, we read "all your > documents belong to us". We need to get the new, restricted scope > down in the policy under section 1.1. It should be "all your documents are belong to us". www.planettribes.com/allyourbase/index.shtml. Thanks for picking this up. Fixing.... > > I can just start revising that -- but I don't want to step on any > toes. I guess I should wait a bit to see if we have consensus. Please feel free to revise it. It's in CVS, if we hadn't want people to change it we wouldn't have added it there (as some DDs do, see below) > Review of Chapter 2 tells me it's ok as is I think. Could use a > little rewriting for smoothness. You're welcome to do this. > > Personally I think in view of our revised ideas about our scope, the > idea of /usr/share/doc/Debian becomes a little dubious. Not all > Debian documents are covered by the DDP policy. No. That's the maint point. If it's a Debian document why on earth is it not under the DDP CVS. I'm sure I'm stepping on many people shoes, many have been handling their documents in other (different) ways, such as the Installation manual, the Developers Reference... Take a look at Bug #64278 or Bug #118592, or Bug #172482 or Bug #106492.... This separation into multiple "islands" each handled by their own DD makes it difficult to have a way to: - make translations and keep them up-to-date - publish documentation on the ftp/web site (both original and translations) - provide packages for offline reading (for both too) And that situation takes us to the point in which translators can't do their work properly, packages with documents get out of date, the website/ftpsite is missing content, and basicly users are not provided with all the information translators/documentation managers have struggled to make for them. We _need_ a common infraestructure, I can't stress that enough. And we need DDs to accept and use that infraestructure, not provide whatever they feel is best when it usually is not. > > I guess this raises a point. If the scope of the DDP Policy is DDP > documents, there might be items in there that we wish to raise to the > level of Debian Policy of Developer's Reference materials (general > Debian documentation best practices, not just applying to DDP). > > I'm happy to incorporate things like this in the Developer's > Reference, although I'd like to review the discussions on > /usr/share/doc/Debian. We might even be able to share text between > the two documents (using CVS and shared included modules). > I don't have any pointers atm. Anyone? > On /usr/share/doc/Debian/, I'm not sure if it's really necessary, > since collection of Debian documentation is already done in a single > section in the doc-base registration and things of that nature. > Again, pointers to discussion on this list or elsewhere would be > appreciated. > Doc-base is not good enough. Excuse me for saying this, but document registration, if not integrated with GNOME/KDE help system as a subsytem is not enough. Please look around in /usr/share/doc to find stuff. Literally. > developers-reference-en > developers-reference-fr This one is preferred. Some DDP documents might be available only on a given language and that might just not be english (see the fr/ section under manuals.sgml). The broader Debian gets the more documents that will be written by non-native english speakers (I believe one such proposal for a spanish document was made a while back). > If you don't mind some radical surgery, I might be able to go through > the document, trimming the scope, and marking sections which should be > destined for policy or best practices as appropriate. > "Put down your visors... lasers coming up" (i.e. go ahead, but don't forget to take content to Developers reference when appropiate) Regards Javi
Attachment:
pgplpXQsYe_jg.pgp
Description: PGP signature