(api) docs for developers

Download (API) Docs for Developers

Post on 13-Jul-2015

1.145 views

Category:

Technology

3 download

Embed Size (px)

TRANSCRIPT

  • Hi, Im Brandon.

    @brandonmwest

    brandon.west@sendgrid.com

    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 cant write a

    single coherent sentence,

    never mind string together a

    paragraph.

  • TYPES of Docs Descriptive

    Reference / Code

    Tutorials

    Interactive

  • Docs developer

    A tech writer isnt enough.

    Ninjas need not apply.

  • Docs as Engineering

  • structureIf your content is not

    organized and easy to find,

    its 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

    Dont document the UI.

    Dont 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

    brandon.west@sendgrid.com

    Docs for developers

    Thanks!