Re: Ruby Docs with annotations and searching

I'm not sure that I agree. Partially because that there are other
large documentation projects out there, PHP and MySql, that work very
well with this format. Maintainers only have to go through the
comments when they are updating the official docs, which is on their
schedule. I don't think they need to continually be monitoring. I also
don't believe that you are going to see much duplication because
comments are separated into very granular areas (by method etc.) and
it will be quick to see the comments that have come before.

--
Conor

On 5/17/06, Sy Ali <[email protected]> wrote:
> 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.
>
>