a documentation crash course, linuxcon 2016

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!