Jutsu or DôOpen documentation: continuous process

than a bodyLinux.conf.au 2015

Raghavendra Prabhu raghavendra.d.prabhu@gmail.com

Percona raghavendra.prabhu@percona.com 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