[
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.
