How to create good documentation?


software developer

Auth0 Inc.


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

product for developers

understand a developer

avoid having them code

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


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!


4. Complete Github READMEs

Github READMEs must be complete!

Our README's secret sauce

- Title

- Description

- Key features

- Installing it

- TL;DR: Using it


- 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

build good documentation

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


Video tutorials

What's next for you?

Thank you for listening

How to create good documentation?