You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@hbase.apache.org by "Todd Lipcon (JIRA)" <ji...@apache.org> on 2010/06/02 01:37:36 UTC
[jira] Created: (HBASE-2650) Consolidate user guide style
documentation
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.
[jira] Commented: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12888048#action_12888048 ]
stack commented on HBASE-2650:
------------------------------
Proposal sounds good by me.
I'm of the docbook persuasion myself (Did the heritrix mvn build generated manuals from src -- see http://crawler.archive.org/articles/developer_manual/index.html).
How'd you get docbook to show like that in the zend website? Its in a frame?
I'm not sure documentation/manual/en is right location in maven. Might want to put it under src/site into a docbook directory or so? We can figure it out (I like the en subdir... jp, cn, fr would be super cool)
This is the nifty maven: http://code.google.com/p/docbkx-tools/ (and its alive).
We should look at the doxia convertion tool. We might be able to run it as part of the site build to generate docbook articles from apt articles for inclusion in an hbase 'book'. Here's the convertion tool: http://maven.apache.org/doxia/doxia-tools/doxia-converter/usage.html
> 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.90.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.
[jira] Commented: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12926637#action_12926637 ]
stack commented on HBASE-2650:
------------------------------
One thing that would be nice would be a search that shows in the manual as per example cited by wade above. I'll make an issue.
> 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
> Assignee: stack
> Fix For: 0.90.0
>
> Attachments: docbk.txt, docbkx-v2.txt
>
>
> 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.
[jira] Commented: (HBASE-2650) Consolidate user guide style
documentation
Posted by "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.
[jira] Commented: (HBASE-2650) Consolidate user guide style
documentation
Posted by "Jonathan Gray (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12890511#action_12890511 ]
Jonathan Gray commented on HBASE-2650:
--------------------------------------
(ability to pass in pom attributes is indeed very sweet)
> 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.90.0
>
> Attachments: docbk.txt
>
>
> 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.
[jira] Assigned: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
stack reassigned HBASE-2650:
----------------------------
Assignee: stack
> 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
> Assignee: stack
> Fix For: 0.90.0
>
> Attachments: docbk.txt, docbkx-v2.txt
>
>
> 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.
[jira] Updated: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
stack updated HBASE-2650:
-------------------------
Attachment: docbk.txt
Here is a patch that adds in mention of the above cited docbook plugin to our pom. This plugin is very nice, developed, well-documented, and under active development. I see no reason why we would ever do documentation in anything but docbook going forward (I tried to write something in 'apt' yesterday and the doc for apt is so bad, in the end I had to resort to casting the doc as xdoc, something that is supposed to be deprecated in mvn2 -- even though mvn2 tells you that if you want to style your doc, use xdoc... not apt). This plugin will process anything put into src/docbkx directory. You can do sweet stuff like pass pom attributes through to the document so you can set an entity variable for things like hbase version, etc (See sample book.xml page included in patch). We can use xincludes to pull articles into the book. It seems to run pretty fast. I think its because its downloaded all stylesheets local.
> 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.90.0
>
> Attachments: docbk.txt
>
>
> 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.
[jira] Updated: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
stack updated HBASE-2650:
-------------------------
Status: Patch Available (was: Open)
Marking patch available so it'll get some attention. Commit of the patch would mean committed to docbook going forward. Looking for reviewers/opinions.
> 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.90.0
>
> Attachments: docbk.txt
>
>
> 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.
[jira] Commented: (HBASE-2650) Consolidate user guide style
documentation
Posted by "Jonathan Gray (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12890510#action_12890510 ]
Jonathan Gray commented on HBASE-2650:
--------------------------------------
Sounds awesome. I'm +1 on standardizing around a single format and based on everything I've heard to this point also +1 on that thing being docbook.
Great work stack.
> 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.90.0
>
> Attachments: docbk.txt
>
>
> 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.
[jira] Commented: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12892149#action_12892149 ]
stack commented on HBASE-2650:
------------------------------
So yeah, I'm committing docbkx-v2 patch above but this by no means should be interpreted that this issue is done.
> 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.90.0
>
> Attachments: docbk.txt, docbkx-v2.txt
>
>
> 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.
[jira] Commented: (HBASE-2650) Consolidate user guide style
documentation
Posted by "Wade Arnold (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12885581#action_12885581 ]
Wade Arnold commented on HBASE-2650:
------------------------------------
I would like to propose a manual to the repository that covers the majority of the getting started, building, deploying articles that really need to keep up to and versioned with releases. This would be different than the general wiki were discussions can flow but would ultimately be promoted to the manual. I would like to propose that we use docbook. It is something that I am familiar with from other open source projects and have used it with publishing companies.
I would like to add a directory to the repository as follows:
hbase/trunk/documentation/manual/en/
I have written some documentation for the zend framework and there system is based on docbook and works pretty well. This is the type of page that I would like to build for HBase.
http://framework.zend.com/manual/en/
http://framework.zend.com/manual/en/zend.amf.server.html
> 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.
[jira] Updated: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
stack updated HBASE-2650:
-------------------------
Attachment: docbkx-v2.txt
I did some more playing with this stuff.
Here's some downsides:
+ If you browse to the docbook 'book' or 'articles', you no longer have the maven surround -- the navbar along the left nor the banner across the top.
+ Configuration done in pom of docbkx stuff applies to all types -- both books and articles -- so if you enable chunking, then while that might be what you want for books (i.e. a page per chapter, it might not be what you want for an article). Maybe we don't want to do articles as docbook because of this and just do the 'book' (On other hand, xdoc and doxia and apt are total crap see previous commentary, so doing them up as docbook though missing navbar and banner is an improvement IMO).
+ I wanted to make a docbook version of an existing xdoc article -- just to show fellas what it'd look like -- but the converter tool won't work for me (http://maven.apache.org/doxia/doxia-tools/doxia-converter/usage.html). It sees like I'm running into an error interpreting/downloading schema but the xsd is properly referenced and extant which makes me think it something dumb the doxia tool is doing.
I'm going to commit this patch just so folks can see what it all looks like in generated site. We can revert no problem if its not to all's liking.
> 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.90.0
>
> Attachments: docbk.txt, docbkx-v2.txt
>
>
> 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.
[jira] Updated: (HBASE-2650) Consolidate user guide style
documentation
Posted by "stack (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/HBASE-2650?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
stack updated HBASE-2650:
-------------------------
Resolution: Fixed
Status: Resolved (was: Patch Available)
Resolving.
The hbase book has been moving along for a while now. It is far from complete but is starting to shape up. It advertises itself as first stop shop for hbase documentation with pointers out to wiki, javadoc, etc., for content not content within.
Need to open other issues for edit and clean up of our wiki moving what belongs in the hbase book there deprecating old content, etc.
Will also be moving some of the javadoc content into the book but thats another JIRA.
> 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
> Assignee: stack
> Fix For: 0.90.0
>
> Attachments: docbk.txt, docbkx-v2.txt
>
>
> 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.