1. 1 hbasecon.com
State of Apache HBase Documentation
Misty Stanley-Jones
Committer, Apache HBase, Apache Software Foundation
Senior Technical Writer, Cloudera

2. 2 hbasecon.com
Overview
 Doc highlights of the past year
 Asciidoc Demo
 How you can get involved

3. 3 hbasecon.com
Why Docs Matter
 Good Product + Bad Documentation = Mediocre Product
 User Experience
 Developer Experience
 Customer Experience
 45-55% of Cloudera HBase customer cases solved by
documentation!
 Two years ago, 20%

4. 4 hbasecon.com
One Year Ago
 HBaseCON 2014, my 2nd week at Cloudera
 Cloudera hired me to focus on and drive HBase documentation
 Hundreds of open, unclaimed, neglected doc JIRAs

5. 5 hbasecon.com
First Year Highlights
 Quickstart
 Blockcache
 Compaction
 Replication
 Developer / Contributor Guidelines
 Content Gaps

6. 6 hbasecon.com
Quickstart
 Previously: Single-host standalone install
 Added:
 Pseudo-distributed and fully-distributed configuration
 HDFS configuration
 Backup masters
 SSH key generation
 More HBase Shell examples

7. 7 hbasecon.com
BlockCache
Blockcache enables you to take advantage of all your memory!
(if you do it right)
 General BlockCache tuning (HBASE-11098, HBASE-11752)
 BucketCache, when to use it (HBASE-11238)
 Compressed BlockCache (HBASE-11939)
 BlockCache Web UI (HBASE-11739)

8. 8 hbasecon.com
Compaction
Misconfigured compaction settings increase the variability of
your cluster’s performance!
 Explaining the compaction algorithms (HBASE-11120) (my very
first HBase JIRA)
 Compaction tuning advice (HBASE-11121, HBASE-11316)
 When and how to manage compaction manually (HBASE-
11324) (hint – don’t!)

9. 9 hbasecon.com
Replication
Replication increases the availability and reliability of your data
(if you do it right)
 Move Replication documentation out of Javadoc into Ref Guide
(HBASE-11522)
 Terminology change – “Master Master”? “Cyclical”? Just talk
about topology. (HBASE-12677)
 Document removal of replication state (start_replication,
start_replication) (HBASE-8844)

10. 10 hbasecon.com
Developer / Contributor Guidelines
High-Availability Release Management!
 Cleaned up and expanded IDE configuration to include IntelliJ
as well as Eclipse (HBASE-11704)
 Got consensus on patch-submission and commit message
guidelines and documented it (HBASE-4593)
 Cleaned up docs for releasing HBase
 Developed a script for publishing the website (HBASE-11951)
 Created docs contribution guidelines (HBASE-11539)

11. 11 hbasecon.com
Other Content Gaps
Recording the HBase folklore
 Scripting with HBase Shell (HBASE-11656, HBASE-11655)
 Hotspotting (HBASE-11682)
 Phases of region splitting (HBASE-12425)
 Setting a split policy (HBASE-12701)
 How ACLs work, and how to test them (HBASE-12421, HBASE-11791)
 How to find all the exposed metrics (HBASE-11607)
 How to report security bugs (HBASE-7126)

12. 12 hbasecon.com
First Year Summary
 We closed 122 HBase Documentation JIRAs between May 1
2014 and May 1 2015.
 Up from 24 the year before
 47 open Documentation JIRAs
 27 unassigned – GO GET ‘EM!

13. 13 hbasecon.com
Why AsciiDoc?
 Plain text!
 Very similar to Markdown (actually a superset)
 Easy theming and PDF rendering
 Reuse real code in docs
 Great editing experience in Github editor

14. 14 hbasecon.com
Github Editing – Where are the docs?

15. 15 hbasecon.com
Github Editing – Edit something

16. 16 hbasecon.com
Github Editing – Preview it

17. 17 hbasecon.com
Github Editing – Preview it

18. 18 hbasecon.com
Github Editing – Submit it

19. 19 hbasecon.com
Github Editing – Nice, clean diff

20. 20 hbasecon.com
Github Editing – Docbook diff

21. 21 hbasecon.com
Asciidoc Guidelines
 Same formatting guidance as code (100 columns, 2 spaces for
indentation, etc)
 http://hbase.apache.org/book.html#appendix_contributing_to_documentation
 Build: mvn clean site -DskipTests
 Independent local build:
asciidoctor –b src/main/asciidoc/book.adoc

22. 22 hbasecon.com
What’s Next?
 HBase 2.0 Reference Guide
 Complete restructure and rewrite
 HBASE-11515
 We need you!
Graphic via @frisco0303

23. 23 hbasecon.com
Questions?
Email: misty@apache.org
Twitter: @mistysj
Claim a Doc JIRA