Home | About | Sematext search-lucene.com search-hadoop.com
 Search Hadoop and all its subprojects:

Switch to Threaded View
Accumulo, mail # dev - Docs with monitor


Copy link to this message
-
Re: Docs with monitor
David Medinets 2013-06-04, 22:32
I'm still hoping for a semantic-based wiki approach.
On Tue, Jun 4, 2013 at 3:55 PM, Keith Turner <[EMAIL PROTECTED]> wrote:

> On Tue, Jun 4, 2013 at 3:36 PM, Christopher <[EMAIL PROTECTED]> wrote:
>
> > That would be nice, but we should avoid relative paths in javadocs
> > that link externally, because they also get packaged in the -javadoc
> > jars, and should be independent.
> >
>
> We could use the structure you discussed for docs on the accumulo site to
> put absolute links into the javadocs.   Would be nice to do this in such a
> way that we could verify the docs w/ a link checker prior to release.
>  Seems like this would require the ability to set the link prefix in one
> place, and then generate docs w/ that prefix.  Not sure how to do this w/
> javadoc.
>
>
> >
> > --
> > Christopher L Tubbs II
> > http://gravatar.com/ctubbsii
> >
> >
> > On Tue, Jun 4, 2013 at 3:25 PM, Keith Turner <[EMAIL PROTECTED]> wrote:
> > > Something I have wanted w/ Accumulo documention is have more linking
> > (i.e.
> > > links to javadoc from usermanual and visa versa).  If we had a standard
> > dir
> > > structure, then we could have relative links between components.
> > >
> > >
> > > On Tue, Jun 4, 2013 at 2:05 PM, Christopher <[EMAIL PROTECTED]>
> wrote:
> > >
> > >> Documentation is spread out everywhere, and it's a bit difficult to
> > >> keep it consistent and up-to-date.
> > >>
> > >> I think we should focus on keeping per-version documentation
> > >> up-to-date on the Accumulo website and in the user manual/book instead
> > >> of relying on the maintenance of random READMEs, docs/*.html on the
> > >> monitor, etc.
> > >>
> > >> I opened one issue (ACCUMULO-1487) related to this, but I'm looking at
> > >> the links in docs/*.html and it seems they are written with the
> > >> assumption that they are being served from the monitor. I'm not sure
> > >> how useful these are. Perhaps it'd be better if these were simply
> > >> removed from the monitor, and replaced with a link to the website
> > >> documentation (link configurable)?
> > >>
> > >> That said, it would probably benefit us to have documentation links
> such
> > >> as:
> > >>
> > >> http://accumulo.apache.org/docs/1.5/ -> points to latest 1.5.x
> > >> http://accumulo.apache.org/docs/1.5.1/
> > >> http://accumulo.apache.org/docs/latest/ -> points to latest overall
> > >> version (menu includes links to older versions)
> > >> http://accumulo.apache.org/docs/ -> redirects to docs/latest
> > >>
> > >> So, this email is about two things, really:
> > >>
> > >> 1) Improve the website with consolidated per-version documentation.
> > >> 2) Get rid of documentation packaged with the monitor.
> > >>
> > >> This doesn't address the consolidation of the various READMEs, but
> > >> those should be addressed at some point also.
> > >>
> > >> I also opened ACCUMULO-1490, ACCUMULO-1491 to deal with this. And, as
> > >> part of improvements for ACCUMULO-935, I already made a separate
> > >> "docs" module that could probably benefit from some further polishing.
> > >>
> > >> Thoughts?
> > >>
> > >> --
> > >> Christopher L Tubbs II
> > >> http://gravatar.com/ctubbsii
> > >>
> >
>