On 2/3/06, Jorge Godoy <[EMAIL PROTECTED]> wrote: > Even though I really like those comments -- and I've even posted some for the > PostgreSQL docs --, one thing that we have to think about is moderating *and* > not starting discussions there. Otherwise we'll end up with pieces of docs > here, there and everywhere (ML, Wiki, Tickets, blogs, etc.). Moderation will > help keeping the correctness of comments and clarifications (doubts should go > to the mailing list and not on the documentation page, it might get something > to make it clearer later...).
Maybe the workflow should be such that comments should be integrated into the text in some fashion and then deleted. It keeps the page neater and easier to read (but still potentially provides information to people while the comments are reviewed). > But I really like the idea to the this. Ah! And I'd advise to add a note > on every page (currently Trac has it only on the documentation playgroung > page...) that all contributions are public domain and if appropriate will be > incorporated in the official documentation at any time or might get erased > from the page (I believe we'll enhance the official pages with clarifications > from one release to the next...). This is one of the bonuses of the new approach: the distinction between official and unofficial pages is very small (a bit-flip). This was something that came up on the CP list: people can create "unofficial docs". Once they're reviewed (possibly edited), they are blessed as official and in the main doc section. That should really help keep the docs up to date. The clarifications from one release to the next is the copy function that i referred to. For example, for TurboGears 0.9, I could start with a 0.8 document, make a copy tagged for 0.9 and start editing. It's effectively like branching in version control, just without any merge facilities. > One thing is for sure: there will be the need for a wiki editor, to keep the > documentation categorized correctly and to remove old stuff -- and, if > moderation is implemented, to approve comments... Yes. Part of my hope for such a tool is that it would make it easier for anyone to help out and maintain the docs. This shouldn't be a difficult tool to create, but my time is already oversubscribed... By the way, if there are people interested in working on this project, I can set up a mailing list and svn repository for it. Kevin
