accumulo-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Christopher Tubbs (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (ACCUMULO-1490) Consolidate documentation
Date Thu, 06 Feb 2014 00:30:11 GMT

    [ https://issues.apache.org/jira/browse/ACCUMULO-1490?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13892815#comment-13892815
] 

Christopher Tubbs commented on ACCUMULO-1490:
---------------------------------------------

I also like the Avro per-release documentation. I'd rather see a focus on a single set of
good web-based documentation, than worry about distribution of that documentation in every
package and in every form (text, PDF, html), so long as it can be easily mirrored. I like
what Avro has done.

However, I also like the idea of a single set of version-controlled documentation for a single
release line (1.5.x, or 2.x)... because documentation should discuss features, and we shouldn't
be adding features in the middle of a release line. If a change is made that affects users
of a particular version, the documentation for its release line can reflect that with a comment.
As an example, documentation for 1.5.x might say something like: "WARNING: this feature has
a bug and doesn't work correctly until 1.5.2".

One of the reasons I really like this idea is because it incorporates the idea that document
improvements improvements in a bugfix release that clarify features in that release line also
apply to previous releases in that same line (in other words, 1.5.3 documentation improvements
are beneficial for 1.5.0 users also). I'd also like to avoid re-releasing updated documents
for bugfix releases that generally don't change anything.

> Consolidate documentation
> -------------------------
>
>                 Key: ACCUMULO-1490
>                 URL: https://issues.apache.org/jira/browse/ACCUMULO-1490
>             Project: Accumulo
>          Issue Type: Improvement
>          Components: docs, monitor
>            Reporter: Christopher Tubbs
>              Labels: Documentation
>             Fix For: 1.6.0
>
>
> Documentation is everywhere, and part of the problem keeping it up-to-date is lack of
a standard way of packaging and presenting it, I think.
> We have:
> # User manual (pdf and html)
> # Example READMEs (plaintext and converted to html)
> # Html docs packaged with the monitor server (but can be published independently, though
I'm not sure the links will work)
> # Generated configuration documentation included with html docs on the monitor
> These should be consolidated to a standard place (I prefer the website).



--
This message was sent by Atlassian JIRA
(v6.1.5#6160)

Mime
View raw message