Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

HBaseCon 2015: State of HBase Docs and How to Contribute

2,267 views

Published on

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.

Published in: Software
  • Be the first to comment

HBaseCon 2015: State of HBase Docs and How to Contribute

  1. 1. 1 hbasecon.com State of Apache HBase Documentation Misty Stanley-Jones Committer, Apache HBase, Apache Software Foundation Senior Technical Writer, Cloudera
  2. 2. 2 hbasecon.com Overview  Doc highlights of the past year  Asciidoc Demo  How you can get involved
  3. 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. 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. 5 hbasecon.com First Year Highlights  Quickstart  Blockcache  Compaction  Replication  Developer / Contributor Guidelines  Content Gaps
  6. 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. 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. 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. 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. 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. 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. 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. 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. 14 hbasecon.com Github Editing – Where are the docs?
  15. 15. 15 hbasecon.com Github Editing – Edit something
  16. 16. 16 hbasecon.com Github Editing – Preview it
  17. 17. 17 hbasecon.com Github Editing – Preview it
  18. 18. 18 hbasecon.com Github Editing – Submit it
  19. 19. 19 hbasecon.com Github Editing – Nice, clean diff
  20. 20. 20 hbasecon.com Github Editing – Docbook diff
  21. 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. 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. 23 hbasecon.com Questions? Email: misty@apache.org Twitter: @mistysj Claim a Doc JIRA

×