Documentation is King

Documentation leads to better code, a better workplace, and a better life.

https://github.com/kennethreitz
http://twitter.com/kennethreitz

Transcript

1. Documentation is King Kenneth Reitz
2. Hi.
3. @kennethreitz
5. github.com/kennethreitz • ~18 serious projects. • 100+ experiments. • OSX-GCC-Installer: 56TB of downloads. • Requests: 3+ million downloads.
6. Other Interests... • Street Photography • Synthesizers and Music Production • World Travel (~140,000 miles last year) • Public Speaker (29 events last year) • Classic Video Games!
7. The Best Things Prime Lenses, Monophonic Synths, Handheld Games... Pen and paper. Mechanical watch. A single carry-on.
8. CONSTRAINTS FOSTER CREATIVITY
9. The Simple Things Prime Lenses, Monophonic Synths, Handheld Games... Pen and paper. Mechanical watch. A single carry-on. Simple! Simple! Simple! Simple! Simple! Simple!
10. pra•gmat•ic |pragˈmatik|, adj: Dealing with things sensibly and realistically in a way that is based on practical rather than theoretical considerations
11. Requests HTTP for Humans
12. The API is all that matters. Everything else is secondary.
13. — Steve Jobs, 1983 People are going to be spending two or three hours a day with these machines — more than they spend with a car.
14. — Steve Jobs, 1983 Software design must be given at least as much consideration as we give automobiles today — if not a lot more.
15. That worked for Apple.
16. Developers spend 8+ hours a day with APIs. Why are they treated di erently?
17. Requests Success • Python is a language built for Humans. • Why should HTTP be non-trivial? • I explored and discovered what I really needed, and built it. • I had a real problem that I solved for myself.
18. Requests Success • At rst, Requests was far from powerful. • But, it deeply resonated with people. • Features grew over time, but the API was never compromised.
19. Developers spend 8+ hours a day with APIs. Build for yourself—a developer.
20. How?
21. Write the Docs.
22. • Before any code is written, write the README — show some examples. • Write some code with the theoretical code that you’ve documented.
23. Paradigm Shift • Instead of engineering something to get the job done, you interact with the problem itself and build an interface that reacts to it. • You discover it. You respond to it.
24. • Great sculptures aren’t engineered or manufactured—they’re discovered. • The sculptor studies and listens to the marble. He identi es with it. • Then, he responds. • Setting free something hidden that inside all along. Sculptures, Etc.
25. • It’s not about a design that will “work” on a phone, tablet, and desktop. • It’s about making something that identi es itself enough to respond to the environment it’s placed in. • Free of arbitrary constraints. Responsive Design
26. Readme-Driven Development? Responsive API Design.
27. Complex Code is Bad • Tight coupling, monolithic codebases. • Lurking, growing technical debt. • Maintenance burden is high. • Self-serving instead of problem-solving.
28. Simple Code is Good • Code solves problems created by humans. • The less code, the less to maintain. • Negative di s are the best di s. • Small, sharp, distributed services.
29. — Pieter Hintjens Simplicity is always better than functionality.
30. What is Open Source? • Transparent groups of distributed developers working together to make software and projects that make the world a better place.
31. Open Source is Epic • We have a unique opportunity to take part in a powerful social movement, creating the tools that are fundamentally changing the world around us. • Social Media, Elections, Journalism, Wikileaks, etc...
32. Documentation is the glue that makes open source possible.
33. Bad Open Source • Appears unmaintained (20+ pull requests). • Fails to solve a clear problem. • Has unclear expectations. (GitX, Facebook SDK, httplib2, hubcap, oauth2, &c)
34. Great Open Source • Solves a clear problem. • Communicates well with users. • Manages expectations realistically. (Jenkins, Python, Django, Pip, Bundler, &c)
35. Great Open Source • Solves a clear problem. • Communicates well with users. • Manages expectations realistically. (Jenkins, Python, Django, Pip, Bundler, &c) Documentation!
36. Internal Codebase Patterns • Components are tightly coupled. • Broad tribal knowledge is required. • Iterative change of components di cult. • Technical debt has a tendency to spread. • Little documentation (if any).
37. Pretend it’s Open Source • Components become concise & decoupled. • Concerns separate themselves. • Best practices emerge (e.g. no creds in code). • Documentation and tests become crucial. • Code can be released at any time.
38. Document All The Things!
39. Documentation = Better Code • Documentation is more important than tests. • It changes the way we think about problems. • Speci cally, explaining concepts to users and fellow developers helps uncover asymmetry in APIs.
40. Asymmetry?
41. Python 2.5 Bytes Unicode ’42’ u’42’
42. Python 2.5 Bytes Unicode ’42’ u’42’ b’42’ ’42’ Python 3.0
43. Python 2.6 Bytes Unicode ’42’, b’42’ u’42’ b’42’ ’42’ Python 3.1
44. Python 2.7 Bytes Unicode ’42’, b’42’ u’42’ b’42’ ’42’, ? Python 3.2
45. Python 2.7 Bytes Unicode ’42’, b’42’ u’42’ b’42’ ’42’, u’42’ Python 3.3 Symmetrical.
46. Just as writing tests helps encourage composable code, writing documentation encourages consistent code.
47. Documentation = Better Workplace • Every design decision should be documented. • Reduces process locks and sync points. • Automates the onboarding process. • Employees can hop from project to project. • Deploy to production without worry. • First step towards automation.
48. Imagine never having to tap on a coworker’s shoulder again.
49. Imagine never getting interrupted by a coworker again.
50. Documentation = Better Lifestyle • Documentation enables asynchronous work ows. • Increased autonomy leads to a happier life. • Fewer interruptions, fewer misunderstandings.
51. Documentation makes the world a better place.
52. Write the Docs ...or the sloth will nd you.
53. github.com/kennethreitz Questions?