Stop wasting developers time

How to create good documentation?

by Martin Gontovnikas

@mgonto

I am a

software developer

from Buenos Aires, Argentina
working at

Auth0 Inc.

making stuff happen
used to be coding

Javascript

all day long
Now I work as a

Developer Advocate

Let's dive into the talk!

Creating good documentation is really hard

Creating good documentation for developers is even harder

So how do we do it?

How's a day in a developer life?

If none of that works

If we want to make a

product for developers

we must

understand a developer

We want to

avoid having them code

something that

doesn't add value

That's what we've been doing at Auth0

And this is what we've learnt

How to make an awesome doc?

- 1. Tailored documentation

- 2. Tailored sample projects

- 3. Embedable Documentation

- 4. Complete Github READMEs

- 5. Things should be easy to find

- 6. Community Driven Docs

- 7. API Explorer

- 8. Easy on the eye

1. Tailored documentation

Copy Paste Friendly

2. Tailored sample projects

Already configured samples

You can do it yourself

auth0/configured-sample-generator

https://auth0.com/docs/node-auth0/master/create-package?path=examples/nodejs-api&type=server&clientId=UKL4zVK6krRwCTeDlbaTqgnhMXZCdB0H

3. Embedable documentation

Documentation should be everywhere!

We write it in Markdown on Github

And we render it with Markdocs anywhere

We use Lodash templating with Session variables

We promote people to help us fix the docs!

You can do the same!

auth0/docs

4. Complete Github READMEs

Github READMEs must be complete!

Our README's secret sauce

- Title

- Description

- Key features

- Installing it

- TL;DR: Using it

- API

- Examples

- Contributing

- Issue reporting

- License

5. Things should be easy to find

6. Community Driven Docs

Community should help you build up your docs!

7. API Explorer

If you have an API, let people use it!

We first did it manually, now we're migrating to Swagger

8. Easy on the eye

Now we know how to

build good documentation

but

how do we write it?

Use numbered steps

Be concise

Put a lot of code

and very little text

Make everything copy pasteable

That was a lot of info!

So, what's next for Auth0?

TripJS Tutorials

EragonJ/Trip.js

Video tutorials

What's next for you?

This is the end of the presentation, so

Thank you for listening

or at least pretending to
This has been

How to create good documentation?

by Martin Gontovnikas

@mgonto