Just to provide a counter view on this point.
------------------------------
Date: Fri, 27 Jul 2007 15:21:55 -0500 From: Rene Rivera <grafikrobot@gmail.com> Subject: Re: [boost] [Important] Boost moving to Subversion on Tuesday, July 31st Message-ID: <46AA53E3.2030500@gmail.com>
Doug Gregor wrote: I prefer the ease-of-use of a Wiki. My hypothesis is that, if we make it really, really, really easy to make improvements to that developer- centric documentation, we'll get better at keeping it up-to-date and relevant.
Wikipedia has proven that idea impractical. Easy editing doesn't produce better docs, just more of them. You need editors, review, etc. to get better docs.
I feel that we could improve on this process slightly and have the best of both worlds. Rene is right easy editing on a wiki does not necessarily improve documentation!! but Doug is also right that by lowering the bar for people to assist/help with writing documentation we can have more up to date documentation and improve on existing documentation. One of the IBD project's; specifically the "Quickbook as a wiki processor" project (http://svn.boost.org/trac/boost/wiki/QuickbookWikiProcessor) could help. We could setup something like officially sanctioned documentation stored on the official www.boost.org website and provide a link to the beta.boost.org (or is it svn.boost.org?) wiki with the caveat that this is community developed documentation and has not been reviewed for correctness (something like the Ubuntu documentation?). Users could go to this location (at their own risk) if they are interested in documentation that might not be as polished or checked over by experts but hopefully find documentation more up to date that could help them! People interested in clarifying, improving or adding to the documentation could also go to this location and start adding or modifying documentation. Periodically (every month, every quarter, every 6 months, every official boost release?) the IBD (assistant) editors (or for library specific documentation the library maintainers (if they are so inclined)): * could review the documentation additions/changes; * seek expert opinion from library maintainers or other experts where it is not simple to determine if the update is correct; * make a diff of the QuickBook file and merge it with the official QuickBook file; * check the changes in and run the official Boost website documentation generation tool chain to update the www.boost.org website pages. Some of the benefits of this include: * Still having officially sanctioned documentation that users can refer to or be directed to; * All interested parties to easily contribute to the documentation process (no installation footprint (except for a web browser) to write and validate documentation); * Potentially lowering the bar for translation efforts; * Library maintainers have the opportunity for patches to improve their documentation; * Have a simple diff file that can be reviewed for changes during the approval process (no HTML mark-up to get in the way); * Potentially use Trac to manage the migration of the diff file's that need to be merged into the official documentation (including comments, review notes and who merged it); * Through the generation of the Quickbook tool chain have a consistent look and feel to all written documentation on the Boost websites. Some of the cons: * We have effectively duplicated our documentation between www.boost.org and beta.boost.org (is there some way to allow the user to click on a button and apply the diff (with the beta content changes) on the same page?); * Library maintainers now need to worry about another location for documentation (can this be mitigated by using the IBD editors?); * Users through ignorance updating the beta documentation with plain wrong advice. Another benefit is potential boost submissions or approved library submissions that have not made a major boost release yet could store their documentation in the beta.boost.org website for review and access in a semi-official capacity which allows interested users/reviews to more easily find this documentation. Peter.