Great Documentation

Why is great documentation important?

• Important for scalability — first line of defense against the tsunami of user questions

• Great marketing tool – great documentation helps attract and sustain communities

• Reflection on the quality of the product. Poor and lazy documentation = poor quality product

What makes great documentation?

• Detailed. Answers any questions the user might be thinking.

• Well organized (specific articles for specific purposes)

• Well-written (proper grammar, spelling, and punctuation)

• Interactivity (code samples, diagrams, screenshots)

• Lots of guidance (walk-throughs, exercises, tutorials)

How to write great documentation?

• Create a list of all the topics you want to cover

• Put yourself in the users’ shoes. Think about what the user might be thinking.

• Use lots of tools: Grammarly, GitBook, Postman, etc.

• Test your documentation yourself. Have other people test it and see if it works for them.

• Use lots of examples.

• Gather feedback from users!