Re: Ruby Docs with annotations and searching

On 5/17/06, Conor Hunt <[email protected]> wrote:
> I modeled this site after the way that the very successful online PHP
> documentation works (and mysql). Their system works like my site.
> Users add comments below sections. Then when the docs are being
> updated the maintainers go through and roll useful user comments into
> the main documentation. This has the benefit of keeping the main
> documentation well formatted and stable. I'd also prefer to keep it
> simple to add comments, no login and no editing.

The comment-method will mean a huge mess of comments and comments on
comments and thread upon thread.. it's a really interesting snapshot
of history, but really terrible to read through.

It's also a horror to maintain.. either someone would have to be
*really* on top of the situation to update documentation by the
minute, or they would have to make a project out of reading all the
comments and revising the docs appropriately.

It gets really bad if they don't have time one day/week/month and the
comments pile up.. then you get all kinds of duplicate comments and
conversation..

imo, collaboratively-edited documentation with revision history ends
up with something cleaner, especially if the mess of revision
conversation / example code is kept somewhere separate.  This makes
regular documentation pages load faster.  Unless the comments were
AJAXified and not loaded by default.

--+

However, the issue of being able to fold these collaborative /
commented docs into the actual documentation is yet another matter.
This means that three branches of documentation have to exist.

1) The official docs
2) The working docs
3) The collaboration / conversation / notes

These could be folded into the same tool -- e.g. a wiki with three
tabs per item.  They could be kept in different systems -- a browsable
official website and links to conversation pages.  Or perhaps some
other method.

However it's done.. life has to be made easy for the official
documentation team as well as for the random visitors who want to help
the docs out.