Documentation at Scale

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.

2eccc4005572c1e2b12a9c00580bc86f?s=128

Kenneth Reitz

May 06, 2014
Tweet

Transcript

  1. Documentation at Scale Kenneth Reitz

  2. Hi.

  3. @kennethreitz

  4. None
  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.
  14. None
  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.

  41. None