Link
Embed
Share
Beginning
This slide
Copy link URL
Copy link URL
Copy iframe embed code
Copy iframe embed code
Copy javascript embed code
Copy javascript embed code
Share
Tweet
Share
Tweet
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~