Documentation at Scale

Information is powerful — every day we see it transform the world around us.

Documentation doesn’t always have to be about a software workflow or open source project — it can be used to develop and convey ideas much larger than yourself. Information architecture is a powerful tool for developing ideas over time. It enables us to evolve and distill information at a much larger scale than a single person or team could ever achieve on their own.

Take these concepts, and apply open source workflow tools like GitHub’s Pull Requests and Write the Docs, and the distributed evolution of ideas and information has never been more accessible.

We’ll explore these concepts, learn how to foster a community of distributed contributors, encourage contributions early on, and more.

Python-Guide.org will be used as an example, a Python-specific knowledge base written by 168 people and accessed by over 50,000 people every month.

Transcript

1. Documentation at Scale Kenneth Reitz
2. Hi.
3. @kennethreitz
5. Python Software
   Foundation
   
6. github.com/kennethreitz • ~18 serious projects. • 100+ experiments. • OSX-GCC-Installer: 56TB of downloads. • Requests: 13.8+ million downloads.
7. Other Interests... • Street Photography & Photojournalism • Synthesizers & Music Production • World Travel (~140,000 miles last year) • Public Speaker (29 events last year)
8. Language
9. Early Human: Alone with self & ideas. Self
10. Spoken Language: Express ideas to others. Self Other
11. Written Language: Persists ideas over time. Self Other Time
12. Human hardware hasn't changed — The software has been upgraded.
13. Communication: One-to-One. At first, language was mostly used for a single person to communicate to another single person, or a small group of people. ! This is no longer the case.
15. Communication: One-to-Many. • After the printing press, a single privileged entity could communicate to the masses. • Newspapers, Books, Television, Radio, etc. • This formed the narrative of "the public". • Very polarizing — unifying and destructive.
16. Communication: Many-to-Many. ?
17. The Internet!
18. Communication: Many-to-Many. • If you have access to the internet, you have access to a universe of information and ideas. • Anyone can publish anything to any number of people, large or small. A level playing field. • The implications of this are huge.
19. Self Other Time
20. Self Other Time Space
21. Self Other Time Space
22. Self Other Time Space Culture Self-Expression Self-Identity H istory
23. Self Other Time Space Culture Self-Expression Self-Identity H istory Social Media Research & Information Creation & Publishing Consumption & Discovery
24. Wikipedia Self Other ?
25. Write the Docs!
26. Information is Powerful • Information is powerful — every day we see it transform the world around us. • Documentation doesn't always have to be about a software workflow or open source project — it can be used to develop and convey ideas much larger than yourself.
27. Documentation at Scale • Information architecture is a powerful tool for developing ideas over time and space. • It enables us to evolve and distill information at a much larger scale than a single person or team could ever achieve on their own.
28. Documentation at Scale • The Open Source Software style of development works because it allows people to create something larger than themselves. • Why are we only doing this with tech? • We should be doing this with everything!
29. For the first time in Human History! We have the technology.
30. The Tools
31. The Tools Are Ready! • Read the Docs + GitHub Pull Requests • Instant version-controlled documentation that anyone in the world can contribute to. • The software development community seems to be a testbed for technology that will soon be mainstream. This has to be one of them.
32. Python-Guide.org • Python-Guide.org uses this workflow. • Continually updated by 156 contributors. • 50,000+ people view it every month. • Originally outlined and continually curated by myself. Just like an open source project.
33. Bigger Than It Seems • A book, written by 156 people from all over the world, updated daily, transparently curated by an author, requiring zero time to publish, and available globally within seconds? • This sounds simple to us. It's revolutionary.
34. Go, Write Docs! • Go and make some repos that contain only prose, no code. Start building some ideas with others — or just yourself. • Topics need not be technical — build docs on philosophy, humanities, literature, arts, sciences, poetry — everything!
35. Go, Build Tools! • There needs to be more competition! • ReStructuredText is amazing, but quite unapproachable for most people. • The same applies to Git and GitHub. • There's much work to be done!
36. Self Other Time Space
37. Time Space Internationalization "Be Cordial" Policy Contribution Guide ! Persistent Archiving Reducing Bus-Factor Fast Revision Merging Other Considerations
38. The world is made language.
39. Become the author.
40. Write the Docs.