A Documentation
Crash Course
…for developers
LinuxCon, Berlin
@chrischinch

What’s one of the first
things you look at
with a new project?

• W
• W
• W
ho are you writing for?
hat are they trying to achieve?
hy are you writing this?
Youhavehopefullyansweredthesebeforedevelopment…

Assume nothing

Refine your
concept(s)

API docs are (not)
always enough

It’s not a manual

Interactivity

Language
Selected highlights in (mostly) English,
sorry…

Involve the reader

“function takes
parameter x and
returns value y”

“You can use
function to return
the value of y based
on x”

Passive vs Active

“function can be
used to return the
number of y based
on x”

“Holiday approval
will be notified in
due course”

Keep it short

“If I Had More
Time, I Would Have
Written a Shorter
Letter”
– Pascal, Locke, Franklin, Thoreau, Cicero, Wilson?

Structure

Consistency

Tools
In brief…

Format and editing

Management and
rendering

Testing, linting and
automating

Write your own

Want More?
• www.meetup.com/Write-The-Docs-
Berlin
• slack.writethedocs.org

–Me (maybe)
“Documentation
isn’t just for
developers”

Thank You!
Chris Ward
contentful.com
gregariousmammal.com
@chrischinch
I have stickers and merchandise!