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
   

   View Slide

2. Hi.
   

   View Slide

3. @kennethreitz
   

   View Slide

4. View Slide

5. Python Software
   Foundation
   

   View Slide

6. github.com/kennethreitz
   • ~18 serious projects.
   • 100+ experiments.
   • OSX-GCC-Installer: 56TB of downloads.
   • Requests: 13.8+ million downloads.
   

   View Slide

7. Other Interests...
   • Street Photography & Photojournalism
   • Synthesizers & Music Production
   • World Travel (~140,000 miles last year)
   • Public Speaker (29 events last year)
   

   View Slide

8. Language
   

   View Slide

9. Early Human:
   Alone with self & ideas.
   Self
   

   View Slide

10. Spoken Language:
    Express ideas to others.
    Self
    Other
    

    View Slide

11. Written Language:
    Persists ideas over time.
    Self
    Other
    Time
    

    View Slide

12. Human hardware hasn't changed —
    The software has been upgraded.
    

    View Slide

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.
    

    View Slide

14. View Slide

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.
    

    View Slide

16. Communication: Many-to-Many.
    ?
    

    View Slide

17. The Internet!
    

    View Slide

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.
    

    View Slide

19. Self
    Other
    Time
    

    View Slide

20. Self
    Other
    Time
    Space
    

    View Slide

21. Self
    Other
    Time
    Space
    

    View Slide

22. Self
    Other
    Time
    Space
    Culture
    Self-Expression
    Self-Identity
    H
    istory
    

    View Slide

23. Self
    Other
    Time
    Space
    Culture
    Self-Expression
    Self-Identity
    H
    istory
    Social Media
    Research &
    Information
    Creation &
    Publishing
    Consumption &
    Discovery
    

    View Slide

24. Wikipedia
    Self
    Other
    ?
    

    View Slide

25. Write the Docs!
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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!
    

    View Slide

29. For the first time in
    Human History!
    We have the technology.
    

    View Slide

30. The Tools
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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!
    

    View Slide

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!
    

    View Slide

36. Self
    Other
    Time
    Space
    

    View Slide

37. Time
    Space
    Internationalization
    "Be Cordial" Policy
    Contribution Guide
    !
    Persistent Archiving
    Reducing Bus-Factor
    Fast Revision Merging
    Other Considerations
    

    View Slide

38. The world is made language.
    

    View Slide

39. Become the author.
    

    View Slide

40. Write the Docs.
    

    View Slide

41. View Slide