(api) docs for developers
TRANSCRIPT
Hi, I’m Brandon.
@brandonmwest
Docs for Developers
Goals of Docs1. Make the user a hero
Goals of Docs2. Let customers self serve
Goals of Docs3. Reduce support overhead
Goals of Docs1. Make the user a hero
2. Let customers self serve
3. Reduce support overhead
TYPES of Docs• Descriptive
• Reference / Code
• Tutorials
• Interactive
Who should Write Docs
“Most engineers can’t write a
single coherent sentence,
never mind string together a
paragraph.”
TYPES of Docs• Descriptive
• Reference / Code
• Tutorials
• Interactive
Docs developer
A tech writer isn’t enough.
Ninjas need not apply.
Docs as Engineering
structureIf your content is not
organized and easy to find,
it’s not as valuable.
MARKUP and FORMAT
The layout and formatting of
the docs are MORE important
than the words.
DOCS ARE MUTABLE
Docs are alive, just
like the code and DB schema
Do not Repeat YOURSELF
Keep it loosely Coupled
Don’t document the UI.
Don’t document third parties.
Tighten the feedback loop• Let users submit feedback.
• Pay attention to secondary
sources, e.g. Stack Overflow
and GitHub.
Do not rely on robots
Automatic documentation is
good... but not good enough.
@brandonmwest
Docs for developers
Thanks!