a documentation crash course, linuxcon 2016
TRANSCRIPT
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?
You have hopefully answered these before development…
Assume nothing
Refine your concept(s)
API docs are (not) always enough
It’s not a manual
Interactivity
LanguageSelected 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
ToolsIn 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!