RFC: Wine Documentation
As part of the Wine 1.0 effort, we've been working on improving the Wine documentation. We have a proposal for a way to overhaul the documentation system, and we'd like some feedback. We start with the following goals: 1. Documentation should be easy to find 2. Documentation should be clear (the user should quickly see the thing that he or she wants, and there should be no confusion as to which document is 'right') 3. Documentation should be consistent (the documentation should look the same whether it is on winehq or on a mirror, or in a tarball). 4. Documentation should be easy to change. We propose the following visible changes: 1. Entry documentation page should be simplified and prioritized 2. Many multiple disconnected (but similar and/or redundant) documents should be merged under a consistent format. 3. Centralize all of the documentation under one CVS point, possibly as a new CVS tree, possibly just as the documentation/ branch of the Wine CVS tree. 4. Switch the FAQ to use a FAQ-O-MATIC, to facilitate updates and changes to it, and to allow the creation of a world editable late breaking bugs section. We've illustrated our basic ideas on a prototype web site, which can be found at http://wine.codeweavers.com/docs/. We also propose the following changes in procedure: 1. All documentation be moved to a central cvs point, and entered as SGML. 2. This CVS tree builds, in a relatively painless way, a full HTML tree to supply the entire contents of www.winehq.com/documentation (said contents can then be rsync'ed to mirror sites). We plan on building this tree every night (we're also going to be co locating wine.codeweavers.com so access to it gets a bit snappier). 3. If it's a separate tree, multiple developers be given commit access to the new tree. I think commit access would be basically granted to any developer who requests it, so long as they have some standing in the community. Access could be arbitrated by a vote of the current developers with commit access. The initial list should include all people who have recently done work on documentation. For developers without commit access, a new mailing list, say, wine-doc-patches, could be set up, but discussion of wine documentation would remain on wine-devel. We've got a prototype of the cvs tree set up on :pserver:wine.codeweavers.com:/winedoc (username cvs, password cvs). I appreciate thoughts and comments. Jer p.s. I hope no one has figured out yet that by posting these long messages I'm just desparately trying to get to the top of the WWN posting list. grin
Re: RFC: Wine Documentation
Jeremy White [EMAIL PROTECTED] writes: 3. If it's a separate tree, multiple developers be given commit access to the new tree. I think commit access would be basically granted to any developer who requests it, so long as they have some standing in the community. Access could be arbitrated by a vote of the current developers with commit access. The initial list should include all people who have recently done work on documentation. For developers without commit access, a new mailing list, say, wine-doc-patches, could be set up, but discussion of wine documentation would remain on wine-devel. We've got a prototype of the cvs tree set up on :pserver:wine.codeweavers.com:/winedoc (username cvs, password cvs). I think it's better to keep the documentation inside the main tree; this way people who change something in the code can update the documentation at the same time. If people have to work with two CVS trees and submit two separate patches to different mailing lists, they simply won't bother fixing the documentation. -- Alexandre Julliard [EMAIL PROTECTED]
Re: RFC: Wine Documentation
On Fri, 15 Sep 2000, Jeremy White wrote: 2. Documentation should be clear (the user should quickly see the thing that he or she wants, and there should be no confusion as to which document is 'right') Sounds good! 4. Switch the FAQ to use a FAQ-O-MATIC, to facilitate updates and changes to it, and to allow the creation of a world editable late breaking bugs section. F-O-M has advantages, but it also has disadvantages. A manually edited FAQ usually will be of higher quality (and more concise), but if there's someone dedicated to maintaining (i.e., regularily checking and cleaning) a F-O-M, this is not a big issue. (Just my experiences...) Gerald -- Gerald "Jerry" [EMAIL PROTECTED] http://www.dbai.tuwien.ac.at/~pfeifer/
Re: RFC: Wine Documentation
Gerald Pfeifer wrote: On Fri, 15 Sep 2000, Jeremy White wrote: 2. Documentation should be clear (the user should quickly see the thing that he or she wants, and there should be no confusion as to which document is 'right') Sounds good! 4. Switch the FAQ to use a FAQ-O-MATIC, to facilitate updates and changes to it, and to allow the creation of a world editable late breaking bugs section. F-O-M has advantages, but it also has disadvantages. A manually edited FAQ usually will be of higher quality (and more concise), but if there's someone dedicated to maintaining (i.e., regularily checking and cleaning) a F-O-M, this is not a big issue. But a manually edited FAQ requires rather constant (or at least consistent) attention, which it is not receiving now. Unless someone is willing to be a more regular FAQ editor than the current WineHQ maintenance staff (of which I'm a member, so I'm not bashing them at all :-)), a FAQ-O-MATIC has a much better chance of being up-to-date. A potential compromise would be to have a manually-edited section and a FAQ-O-MATIC section, with good content occasionally pulled from the world-updatable section into the "official" section. -- James Juran [EMAIL PROTECTED]
Re: [Re: RFC: Wine Documentation]
On Fri, Sep 15, 2000 at 08:41:37PM -0400, Douglas J. Hunley wrote: James Juran wrote: But a manually edited FAQ requires rather constant (or at least consistent) attention, which it is not receiving now. Unless someone is willing to be a more regular FAQ editor than the current WineHQ maintenance staff (of which I'm a member, so I'm not bashing them at all :-)), a FAQ-O-MATIC has a much better chance of being up-to-date. A potential compromise would be to have a manually-edited section and a FAQ-O-MATIC section, with good content occasionally pulled from the world-updatable section into the "official" section. what kind of qualifications would make a good human faq editor? I'm not a programmer, but I'd like to do something for this project... Hey, that's exactly what I've been searching for ! ;-)) I think the only qualifications are: - listening to the newsgroup and to the IRC channel - remembering all frequently asked questions and trying to write them down in a rather clear way Andreas Mohr
