Successfully reported this slideshow.

HBaseCon 2015: State of HBase Docs and How to Contribute

1

Share

1 of 23
1 of 23

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

Related Audiobooks

Free with a 14 day trial from Scribd

See all

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

Editor's Notes

  • Each open JIRA represents at least one (probably hundreds!) of confused, discouraged users.
  • Single-host: not production-ready, high risk of data loss
  • HBASE-8844 undocumented for +1 year!
  • Talk a bit about the website problem

    Talk a bit about scripting
  • Because you are the key to great HBase documentation!
  • ×