| Who is your audience? Folks using your API or folks who are going to dive into your codebase and contribute to it? For folks using your API, there are two types of documentation you want: 1) Tutorial: Documentation that guides the user through a few steps of working with the API. This should be an integrated experience. The aim is to help a user build a mental model of your project and introduce them to the shape of the major parts of your API. Example: https://developer.gocardless.com/getting-started/api/introdu... Since you're doing this for a library that you can write automated tests for, you should consider showing your user how to test. This helps prevent a user from getting lost and gives them a clearer way to integrate with the rest of their tooling. 2) Reference: Documentation that someone can use to look up the answer to a specific question that they have. This is not an integrated experience but should integrate well with their workflow when building something and searching for answers. The goal here is to be highly searchable, which requires thinking about what words they would look for when trying to find it. Example: https://developer.gocardless.com/api-reference/ This is something I love thinking/talking about, so feel free to email me if you want to videochat and bounce ideas off me. My email is in my profile. |