[boost] Quality doc's and Wiki's (was Re: [Important] Boost moving to Subversion on Tuesday, July 31st)

From: Peter Foley (peter_at_[hidden])
Date: 2007-07-27 22:38:24

Just to provide a counter view on this point.

> ------------------------------
> 
> Date: Fri, 27 Jul 2007 15:21:55 -0500
> From: Rene Rivera <grafikrobot_at_[hidden]>
> Subject: Re: [boost] [Important] Boost moving to Subversion on
> 	Tuesday, July 31st
> Message-ID: <46AA53E3.2030500_at_[hidden]>
>
> > 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.