[jira] Commented: (HBASE-2650) Consolidate user guide style documentation

["stack (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12874434#action_12874434 ] 

stack commented on HBASE-2650:
------------------------------

There are tiers of doc. that I see.  Trouble is in defining the boundaries (and avoiding duplication).  Would be good too if we could avoid doing a format type per tier.   Also (stating obvious), doc needs  to be versioned and go along w/ the version it describes.

Here's a first cut at tiers:

1. Java packages need documentation; e.g. see mapreduce package for ok example and then filter package for an example of a package sorely lacking... needs a description of what package is with examples of how to do filters.
2. Above javadoc, for notions that are grander than any single package or that are not hard description of code but are prescriptive or descriptive of a system that encompasses more than just what is in java, then we should write articles.  Current examples are the how-to for windows and metrics.  These are currently done in xdoc format.  I'd argue that most of what is currently up in the wiki needs to be brought down and made into articles.
3. Beyond articles I see manuals which are comprehensive views on the system written to suit different audiences: programmers, operators, etc.  The HBase Architecture should be done as a manual.

The wiki has its place.  Its good for supporting projects and for lists of things that cut across versions such as the list of hbase presentations or supporting projects (so, its the exception to the 'needs to be versioned' stated above).  Its also good for the ephermerals -- roadmaps -- and for working on first cuts at articles.  

Of note, we are also at a juncture.  With our next major release, we'll be dumping forrest.  We'll be generating our site with maven.  It uses doxia plugin.  Doxia can do our xdoc articles but xdoc was deprecated years ago.  We can keep going in doxia or write apt.  Doxia has convertion tools for going between formats which should help if we want to aggregate articles up in manuals.

For manuals I'm partial to docbook.  There is a nice docbook plugin for maven.  We could have it run as part of site generation, or not.  Would be cool if we could make it so articles could be inserted into manuals (when applicable).  The doxia convertion tool claims docbook output but its docbook ability is poo-poo'd up on the docbook tools maven plugin website.



> Consolidate user guide style documentation
> ------------------------------------------
>
>                 Key: HBASE-2650
>                 URL: https://issues.apache.org/jira/browse/HBASE-2650
>             Project: HBase
>          Issue Type: Task
>          Components: documentation
>            Reporter: Todd Lipcon
>             Fix For: 0.21.0
>
>
> It would be great to clean up our documentation prior to the next major release. We have various bits of docs strewn throughout the JavaDoc, but it's a lot of "hidden gems" (eg the mapreduce package docs) whereas a separate "programmers guide" would be a lot better.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.