Documentation for Fun and Profit

Good documentation is vital in helping others understand what your code does, why, and how they should use it.

I want to show you how to produce beautiful documentation, write better copy, and how documentation helps market your code.

Transcript

1. Documentation for fun and profit
2. James Aitken UI/UX Team Leader – UK2Group @LoonyPandora
3. You need good documentation
4. But hate writing it…
5. CHEAT!
6. What is documentation?
7. Code Comments?
8. PyDoc RDoc TomDoc Docco Rocco Pycco PHPDoc JavaDoc YARD Doxygen JSDoc Epydoc CSSDoc KSS StyleDoc Other Languages
9. Not in Perl
10. Documentation = High Level =head2 validate_email This method determines whether an email address is valid or not
11. Comments = Low Level # Use a naive regex to check emails # because I hate maintenance devs sub validate_email {
13. POD Plain Old Documentation
14. Markup language, like HTML
15. POD Sucks
16. POD Sucks (On Purpose)
17. “The intent is simplicity of use, not power of expression” perlpod
18. POD is everywhere
19. STEP 1 Know your audience
20. What is good documentation
21. Good Docs Must Be Clear Complete Concise
22. Good Docs Answer Input Output Errors
23. Missing one thing…
24. Keep the docs up to date!
25. Laziness Impatience Hubris
26. “I’ll write the docs up tomorrow” everyone
27. “Too much to do. Docs can wait” everyone
28. “The code is self-explanatory” everyone
29. MORE CODE!
30. “Why is the documentation segfaulting?” future you
31. MORE CODE! LESS CODE!
32. “The intent is simplicity of use, not power of expression” perlpod
33. CHEAT!
34. Documentation needs a killer feature
36. “I thought it was pointless at first, but now I can’t live without it” colleague
37. 82.4%* of people read POD unparsed * made up statistic
38. Like coding without ‘strict’ on
39. Readable docs = Useful docs
40. We’re engineers, not designers…
42. CHEAT!
43. POD::HTML5::Browser
44. POD::HTML5::Browser (soon)
46. Put on your VCS server Generate on every commit
47. Push to GitHub gh-pages branch
48. Dist::Zilla plugin coming soon
49. STEP 2 Dogfood your docs
50. I’m the only person on my team, I don’t care.
51. Documentation Driven Development
53. Makes you think before you code
54. Thinking is good
55. STEP 3 ???
56. Use your docs as a marketing tool
57. Better Docs = Higher perceived quality
59. Abstract Synopsis cpanminus Name
60. Use GitHub pages
61. STEP 4 Profit!
62. Docs are high-level Input, Output, Errors Read docs in rendered format When in doubt, cheat. SUMMARY
63. ~FIN~