Slide 1
Slide 1 text
Documentation at Scale
Kenneth Reitz
Slide 2
Slide 2 text
Hi.
Slide 3
Slide 3 text
@kennethreitz
Slide 4
Slide 4 text
No content
Slide 5
Slide 5 text
Python Software
Foundation
Slide 6
Slide 6 text
github.com/kennethreitz
• ~18 serious projects.
• 100+ experiments.
• OSX-GCC-Installer: 56TB of downloads.
• Requests: 13.8+ million downloads.
Slide 7
Slide 7 text
Other Interests...
• Street Photography & Photojournalism
• Synthesizers & Music Production
• World Travel (~140,000 miles last year)
• Public Speaker (29 events last year)
Slide 8
Slide 8 text
Language
Slide 9
Slide 9 text
Early Human:
Alone with self & ideas.
Self
Slide 10
Slide 10 text
Spoken Language:
Express ideas to others.
Self
Other
Slide 11
Slide 11 text
Written Language:
Persists ideas over time.
Self
Other
Time
Slide 12
Slide 12 text
Human hardware hasn't changed —
The software has been upgraded.
Slide 13
Slide 13 text
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.
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
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.
Slide 16
Slide 16 text
Communication: Many-to-Many.
?
Slide 17
Slide 17 text
The Internet!
Slide 18
Slide 18 text
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.
Slide 19
Slide 19 text
Self
Other
Time
Slide 20
Slide 20 text
Self
Other
Time
Space
Slide 21
Slide 21 text
Self
Other
Time
Space
Slide 22
Slide 22 text
Self
Other
Time
Space
Culture
Self-Expression
Self-Identity
H
istory
Slide 23
Slide 23 text
Self
Other
Time
Space
Culture
Self-Expression
Self-Identity
H
istory
Social Media
Research &
Information
Creation &
Publishing
Consumption &
Discovery
Slide 24
Slide 24 text
Wikipedia
Self
Other
?
Slide 25
Slide 25 text
Write the Docs!
Slide 26
Slide 26 text
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.
Slide 27
Slide 27 text
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.
Slide 28
Slide 28 text
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!
Slide 29
Slide 29 text
For the first time in
Human History!
We have the technology.
Slide 30
Slide 30 text
The Tools
Slide 31
Slide 31 text
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.
Slide 32
Slide 32 text
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.
Slide 33
Slide 33 text
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.
Slide 34
Slide 34 text
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!
Slide 35
Slide 35 text
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!
Slide 36
Slide 36 text
Self
Other
Time
Space
Slide 37
Slide 37 text
Time
Space
Internationalization
"Be Cordial" Policy
Contribution Guide
!
Persistent Archiving
Reducing Bus-Factor
Fast Revision Merging
Other Considerations
Slide 38
Slide 38 text
The world is made language.
Slide 39
Slide 39 text
Become the author.
Slide 40
Slide 40 text
Write the Docs.
Slide 41
Slide 41 text
No content