[I'm cc:'ing this to debian-devel also, to give interested parties enough time to sign up on the new list] Susan wrote: > At the suggestion of folks listed above, a mailing list has been set up > called "debian-doc@lists.debian.org". Thanks to Pete Templin for his > timely help! Right on! It's about time we created a Debian documentation list. > There are several motives for setting up this list: There currently > exists no user manual, or set of manuals, per se; the FAQ is not an > appropriate substitute for such a manual. (This mailing list is partly > a result of the fact that the current FAQ is being re-written and > greatly expanded, due to the lack of other documentation. It is now > widely agreed that much of the information in the FAQ should be > transferred to conventional manuals.) > > Before proceeding too far, it is worthwhile to spend some time defining > initial goals. To me, one way to proceed is by asking, How should the > current documentation set differ, for example, from the excellent Linux > HOWTO's? My answers are: > > a) To optimize the use of both the writers' time and the readers' time, > it will be necessary to exercise a high degree of interlinking, which is > not common to the HOWTO documents. I'd like to see a format where users would be encouraged to submit new documents that could easily be linked in to the documentation. I'd like to initially focus on generating on-line HTML (and text file) documentation. When we get a significant chunk of documentation written, then we can work on some other formats of documentation (like hardcopy) based on the content that we've already assembled. > b) Eventually, the Debian WWW site, the Debian FAQ, the Debian documentation > system, (including the policy and programmer's manuals), the evolving > Debian FTP archives, and dwww should all work together and synergistically. I'm particularily interested in people's ideas for dwww, since I'm actively maintaining and developing it. In a day or two, I'll post some of my ideas for dwww, and we can discuss how it fits in with the overall design of the documentation. There are lots of issues: interfacing to the packaging system/menu system, internationalization, full text searching, plug-ins, etc. I'd also like to make it clear that dwww is basically an "open" package, and anybody who would like to contribute to it is welcome to. I'm planning to build a "plug-in" type of architecture into it so that anyone can build systems that work with it. > c) The Debian documentation should contain information customized for > the Debian system; it should not contain any details that are only > relevant to foreign systems. For example, if a Debian package <foo> is > set up so that when it's installed it will already have certain > configuration files or some default operation, then the user should just > be informed of that setup, rather than exposed to all of the possible > setups that he might consider. Yes. Sounds like a job for dwww. Personally, I was planning on developing a package containing my personal notes on the various Debian packages, and making it work as a "plug-in" for the dwww system. Perhaps this idea could be expanded so that anyone could contribute. > d) The Debian documents should be tunable (IMHO) to the user's needs, e.g., > if he has all the documentation present on his own or a local system, > then links in his documentation should point to links on that local system, > except where external links are absolutely demanded. This idea will > need a lot of refinement in order to define _except_. I want to propose an addition to dpkg which would enable a user to install the documentation only from a package. I'd love to install the documentation for every Debian package on dwww.jimpick.com as a service to the Debian community. > These points need to be discussed and refined. Once that's done, then > we can begin to design the documents, set up some prototypes or examples, > and then (hopefully) divide the work. I don't know about assigning tasks to people, but if we provided an environment where people received credit and recognition for the work they do in providing documentation - similar in the way that we honour package developers - then I think people will contribute. Of course, we should also build an infrastructure that makes it easy. > On the other hand, if this strikes readers as a bad way to proceed, > then please offer (on debian-doc) an alternative procedure. Sounds like a good start to me. :-) Cheers, - Jim
Attachment:
pgpqIIH4Ew5YD.pgp
Description: PGP signature