On Tue, Jun 4, 2013 at 3:36 PM, Christopher <ctubb...@apache.org> 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 <ke...@deenlo.com> 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 <ctubb...@apache.org> 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 > >> >
