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>
