Jutsu or DôOpen documentation: continuous process
than a bodyLinux.conf.au 2015
Raghavendra Prabhu [email protected]
Percona [email protected] randomsurfer wnohang.net rdprabhu ronin13
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
Ad-hoc documentation
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
Introduction
Projects
▶ Redis▶ Go/Python/Haskell/Perl▶ Docker▶ Linux kernel
Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 5 / 24
Keep it fresh
Factors
Keep it fresh
▶ Version control▶ Timeline▶ Develop in unison
♦ perldoc
Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 7 / 24
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
Factors
Management :: Formats
▶ RST▶ Markdown▶ Wiki?▶ man/tex/info▶ Which is better
Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 9 / 24
Factors
Management :: Tools
▶ Doxygen▶ Sphinx▶ pandoc▶ Haddock▶ perldoc
Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 10 / 24
Attribution!
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
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
Normalization
Factors
Normalisation
▶ What is this▶ Is denormalized always good▶ Maintenance and deduplication▶ Embedding
Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 15 / 24
Dialectics
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
Learning from Patterns
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
Consumers
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
Factors
Who uses it
▶ Architect♦ Integration♦ Interface
▶ Devops♦ Troubleshooting♦ Reference
Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 22 / 24
Epilogue
Further Reading
▶ https://readthedocs.org/▶ http://docs.writethedocs.org/
Raghavendra Prabhu (Percona) Jutsu or Dô 12 January, 2015 23 / 24
Epilogue
About
▶ /me: Raghavendra Prabhu, Product Lead, Percona XtraDBCluster, 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
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
Top Related