Slide 1

Slide 1 text

Documentation for fun and profit

Slide 2

Slide 2 text

James Aitken UI/UX Team Leader – UK2Group @LoonyPandora

Slide 3

Slide 3 text

You need good documentation

Slide 4

Slide 4 text

But hate writing it…

Slide 5

Slide 5 text

CHEAT!

Slide 6

Slide 6 text

What is documentation?

Slide 7

Slide 7 text

Code Comments?

Slide 8

Slide 8 text

PyDoc RDoc TomDoc Docco Rocco Pycco PHPDoc JavaDoc YARD Doxygen JSDoc Epydoc CSSDoc KSS StyleDoc Other Languages

Slide 9

Slide 9 text

Not in Perl

Slide 10

Slide 10 text

Documentation = High Level =head2 validate_email This method determines whether an email address is valid or not

Slide 11

Slide 11 text

Comments = Low Level # Use a naive regex to check emails # because I hate maintenance devs sub validate_email {

Slide 12

Slide 12 text

No content

Slide 13

Slide 13 text

POD Plain Old Documentation

Slide 14

Slide 14 text

Markup language, like HTML

Slide 15

Slide 15 text

POD Sucks

Slide 16

Slide 16 text

POD Sucks (On Purpose)

Slide 17

Slide 17 text

“The intent is simplicity of use, not power of expression” perlpod

Slide 18

Slide 18 text

POD is everywhere

Slide 19

Slide 19 text

STEP 1 Know your audience

Slide 20

Slide 20 text

What is good documentation

Slide 21

Slide 21 text

Good Docs Must Be Clear Complete Concise

Slide 22

Slide 22 text

Good Docs Answer Input Output Errors

Slide 23

Slide 23 text

Missing one thing…

Slide 24

Slide 24 text

Keep the docs up to date!

Slide 25

Slide 25 text

Laziness Impatience Hubris

Slide 26

Slide 26 text

“I’ll write the docs up tomorrow” everyone

Slide 27

Slide 27 text

“Too much to do. Docs can wait” everyone

Slide 28

Slide 28 text

“The code is self-explanatory” everyone

Slide 29

Slide 29 text

MORE CODE!

Slide 30

Slide 30 text

“Why is the documentation segfaulting?” future you

Slide 31

Slide 31 text

MORE CODE! LESS CODE!

Slide 32

Slide 32 text

“The intent is simplicity of use, not power of expression” perlpod

Slide 33

Slide 33 text

CHEAT!

Slide 34

Slide 34 text

Documentation needs a killer feature

Slide 35

Slide 35 text

No content

Slide 36

Slide 36 text

“I thought it was pointless at first, but now I can’t live without it” colleague

Slide 37

Slide 37 text

82.4%* of people read POD unparsed * made up statistic

Slide 38

Slide 38 text

Like coding without ‘strict’ on

Slide 39

Slide 39 text

Readable docs = Useful docs

Slide 40

Slide 40 text

We’re engineers, not designers…

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

CHEAT!

Slide 43

Slide 43 text

POD::HTML5::Browser

Slide 44

Slide 44 text

POD::HTML5::Browser (soon)

Slide 45

Slide 45 text

No content

Slide 46

Slide 46 text

Put on your VCS server Generate on every commit

Slide 47

Slide 47 text

Push to GitHub gh-pages branch

Slide 48

Slide 48 text

Dist::Zilla plugin coming soon

Slide 49

Slide 49 text

STEP 2 Dogfood your docs

Slide 50

Slide 50 text

I’m the only person on my team, I don’t care.

Slide 51

Slide 51 text

Documentation Driven Development

Slide 52

Slide 52 text

No content

Slide 53

Slide 53 text

Makes you think before you code

Slide 54

Slide 54 text

Thinking is good

Slide 55

Slide 55 text

STEP 3 ???

Slide 56

Slide 56 text

Use your docs as a marketing tool

Slide 57

Slide 57 text

Better Docs = Higher perceived quality

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

Abstract Synopsis cpanminus Name

Slide 60

Slide 60 text

Use GitHub pages

Slide 61

Slide 61 text

STEP 4 Profit!

Slide 62

Slide 62 text

Docs are high-level Input, Output, Errors Read docs in rendered format When in doubt, cheat. SUMMARY

Slide 63

Slide 63 text

~FIN~