Documentation Versions and wiki

[Grant Ingersoll <gs...@apache.org>]

One of the problems of relying on a wiki for documentation is that it is hard to know which docs go with which version of the code.  To date, we've flagged things, but this only gets us so far and becomes a burden as more versions accumulate (see Solr).  Has anyone looked at Confluence's versioning capabilities?  I'm pretty sure we can start carving out version specific docs.  Might be good to start planning for this now.  I'm not super concerned about for 0.x, but once we hit 1.0, I think it would be wise to have a system in place that we can rely on.

Thoughts?

-Grant

Re: Documentation Versions and wiki

[Isabel Drost <is...@apache.org>]

On 03.07.2010 Robin Anil wrote:
> Javadoc is the best way to go in terms of versioned documentation. Wiki
> pages can link to each version. We haven't enforced package summary nor are
> the javadoc comments proofread to check whether they are clear enough for
> any developer to understand. So for 1.0 having package summaries and proof
> read javadoc should be a blocker. The way I see it, wiki will serve as a
> way to ease generation of the doc due to its open nature

Javadocs are fine for more experienced developers. However we do have some 
"Getting started", "HowTo start individual algorithms" and such in the wiki that 
would be nice to have for each release.

You are right in that the wiki lowers the bar for adding to the documentation, 
however I think we should at least distribute some overview or getting started 
with each release. Not sure this can (or even should) be covered in the Javadocs 
alone.

Isabel

Re: Documentation Versions and wiki

[Robin Anil <ro...@gmail.com>]

Javadoc is the best way to go in terms of versioned documentation. Wiki
pages can link to each version. We haven't enforced package summary nor are
the javadoc comments proofread to check whether they are clear enough for
any developer to understand. So for 1.0 having package summaries and proof
read javadoc should be a blocker. The way I see it, wiki will serve as a way
to ease generation of the doc due to its open nature

Robin


On Thu, Jul 1, 2010 at 10:42 PM, Ted Dunning <te...@gmail.com> wrote:

> Getting some sort of easy solution for version sooner rather than later is
> definitely good.
>
> On Thu, Jul 1, 2010 at 8:31 AM, Grant Ingersoll <gs...@apache.org>
> wrote:
>
> > One of the problems of relying on a wiki for documentation is that it is
> > hard to know which docs go with which version of the code.  To date,
> we've
> > flagged things, but this only gets us so far and becomes a burden as more
> > versions accumulate (see Solr).  Has anyone looked at Confluence's
> > versioning capabilities?  I'm pretty sure we can start carving out
> version
> > specific docs.  Might be good to start planning for this now.  I'm not
> super
> > concerned about for 0.x, but once we hit 1.0, I think it would be wise to
> > have a system in place that we can rely on.
> >
> > Thoughts?
> >
> > -Grant
>

Re: Documentation Versions and wiki

[Ted Dunning <te...@gmail.com>]

Getting some sort of easy solution for version sooner rather than later is
definitely good.

On Thu, Jul 1, 2010 at 8:31 AM, Grant Ingersoll <gs...@apache.org> wrote:

> One of the problems of relying on a wiki for documentation is that it is
> hard to know which docs go with which version of the code.  To date, we've
> flagged things, but this only gets us so far and becomes a burden as more
> versions accumulate (see Solr).  Has anyone looked at Confluence's
> versioning capabilities?  I'm pretty sure we can start carving out version
> specific docs.  Might be good to start planning for this now.  I'm not super
> concerned about for 0.x, but once we hit 1.0, I think it would be wise to
> have a system in place that we can rely on.
>
> Thoughts?
>
> -Grant