Non-reference documentation: Writing the overview

If the project is brand new or hasn't had a technical writer before, it most likely lacks an overview. You should write one.

The overview should tell your users what they need to know before adopting or before using the API.

Every product needs an overview to provide those answers, because without one a small number of prospects will never become users. Some users have a very specific requirement that they want the product to fill, or they just have a need to understand your software before they trust it.

If the entire product is an API, the overview is straightforward. A product that already has an overview and that spans multiple interfaces (a web app, command line clients, plug-ins, and an API, for example), still needs to explain some things about the API. You might want to call that document an introduction, or something else, to avoid confusing with the product overview.

The API overview answers broad conceptual questions about the API (technical specifics are in the reference docs), and the questions will be different depending on what the API does and who uses it.

Some questions you may need to answer:

• What does the API do? (What does not do?)

• How does it work? (What is the architecture? What technology is under the hood?)

• What key concepts does the user need to understand? (Is there a data model? What services are available?)

• When and why would someone want to use the API?

• What problem does it solve?

• What are the typical use scenarios? (Who uses it and what are they trying to accomplish?)

Some other minor questions:

• What docs are available?

• Where do you find critical info about auth, compatibility with other software and platforms, data formats, etc.

• Where to find out about administrative tasks like creating users and groups, assigning roles and permissions, and using external identity providers.