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.

Jutsu or Dô: Open documentation: continuous process than a body

276 views

Published on

This talk is about open source documentation and how it can be improved for the community!

Video: https://www.youtube.com/watch?v=sG6jORFwhEA&list=PLctlsn9Gs8wbx47tuhxuNytdrsDf_LWI2&index=3

Playlist: http://www.youtube.com/playlist?list=PLctlsn9Gs8wbx47tuhxuNytdrsDf_LWI2

Published in: Engineering
  • Be the first to comment

  • Be the first to like this

Jutsu or Dô: Open documentation: continuous process than a body

  1. 1. Jutsu or Dô Open documentation: continuous process than a body Linux.conf.au 2015 Raghavendra Prabhu  raghavendra.d.prabhu@gmail.com Percona  raghavendra.prabhu@percona.com  randomsurfer  wnohang.net  rdprabhu  ronin13
  2. 2. Introduction Lucid documentation can ▶ Help in rapid community growth ▶ Attract more contributors ▶ Enhance quality of code ▶ Help in bug fixes Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 2 / 24
  3. 3. Ad-hoc documentation
  4. 4. Introduction Conversely, Poor documentation would... ▶ Repel users and community ▶ Lead to a less understood code ▶ Spurious bug reports ▶ Retard growth of project Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 4 / 24
  5. 5. Introduction Projects ▶ Redis ▶ Go/Python/Haskell/Perl ▶ Docker ▶ Linux kernel Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 5 / 24
  6. 6. Keep it fresh
  7. 7. Factors Keep it fresh ▶ Version control ▶ Timeline ▶ Develop in unison ♦ perldoc Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 7 / 24
  8. 8. Factors Management ▶ Continuous Integration ▶ Feedback ▶ Packaged documentation ▶ Documentation Testing ▶ Reverse links from code - hackage Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 8 / 24
  9. 9. Factors Management :: Formats ▶ RST ▶ Markdown ▶ Wiki? ▶ man/tex/info ▶ Which is better Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 9 / 24
  10. 10. Factors Management :: Tools ▶ Doxygen ▶ Sphinx ▶ pandoc ▶ Haddock ▶ perldoc Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 10 / 24
  11. 11. Attribution!
  12. 12. Factors Attribution ▶ Unlike code, not much and formal ▶ Importance to project ▶ Incentive ▶ Feedback loop Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 12 / 24
  13. 13. Factors Personal Touch ▶ Preference towards blogs ▶ Less Mechanical ▶ Speak directly to the reader ▶ More ’How To’ Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 13 / 24
  14. 14. Normalization
  15. 15. Factors Normalisation ▶ What is this ▶ Is denormalized always good ▶ Maintenance and deduplication ▶ Embedding Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 15 / 24
  16. 16. Dialectics
  17. 17. Factors Dialectical Approach ▶ or FAQ ▶ Flow of human thinking ▶ Troubleshooting ▶ Also, for beginners ▶ ‘Learning the hard way‘ Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 17 / 24
  18. 18. Learning from Patterns
  19. 19. Factors Examples ▶ Humans:Examples :: Machines:Algorithm ♦ Machine Learning ▶ Examples always help ▶ Quick testing ▶ Coverage Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 19 / 24
  20. 20. Consumers
  21. 21. Factors Who uses it ▶ End user ♦ Simplicity ♦ Prior knowledge ▶ Developer ♦ Code Comments ♦ Design documents Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 21 / 24
  22. 22. Factors Who uses it ▶ Architect ♦ Integration ♦ Interface ▶ Devops ♦ Troubleshooting ♦ Reference Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 22 / 24
  23. 23. Epilogue Further Reading ▶ https://readthedocs.org/ ▶ http://docs.writethedocs.org/ Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 23 / 24
  24. 24. Epilogue About ▶ /me: Raghavendra Prabhu, Product Lead, Percona XtraDB Cluster, Percona. ▶ Slides will be at slideshare.net/slidunder. ▶ About.me: raghavendra.prabhu ▶ Keybase.io: rdprabhu ▶ Presentation under CC BY-SA 4.0 Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 24 / 24
  25. 25. Epilogue Image Credits ▶ https://www.flickr.com/photos/smemon/4902523202 ▶ https://www.flickr.com/photos/ekampf/341734410 ▶ https://www.flickr.com/photos/ecstaticist/6303689386 ▶ https://www.flickr.com/photos/lentina_x/3596663014/ ▶ http://www.aibn.uq.edu.au/roles-and-responsibilities ▶ http://faculty.mercer.edu/spears_a/studentpages/pattern/website.htm ▶ http://mashable.com/2013/10/03/video-assets-creative-commons/ ▶ https://en.wikipedia.org/wiki/Snowflake_schema ▶ https://www.flickr.com/photos/stephanie_in_love/5525689604/ Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 25 / 24

×