In this session, learn about the move to Asciidoc in HBase docs, some of the other notable changes lately, and things we've done to make it easier for you to contribute to the docs.

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