You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@accumulo.apache.org by Christopher <ct...@apache.org> on 2013/06/04 20:05:10 UTC
Docs with monitor
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
Re: Docs with monitor
Posted by David Medinets <da...@gmail.com>.
I'm still hoping for a semantic-based wiki approach.
On Tue, Jun 4, 2013 at 3:55 PM, Keith Turner <ke...@deenlo.com> wrote:
> On Tue, Jun 4, 2013 at 3:36 PM, Christopher <ct...@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 <ct...@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
> > >>
> >
>
Re: Docs with monitor
Posted by Keith Turner <ke...@deenlo.com>.
On Tue, Jun 4, 2013 at 3:36 PM, Christopher <ct...@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 <ct...@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
> >>
>
Re: Docs with monitor
Posted by Christopher <ct...@apache.org>.
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.
--
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 <ct...@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
>>
Re: Docs with monitor
Posted by Keith Turner <ke...@deenlo.com>.
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 <ct...@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
>