Skip to content

overview.md

Latest commit

 

History

History
31 lines (19 loc) · 2.22 KB

overview.md

File metadata and controls

31 lines (19 loc) · 2.22 KB

The Overview

Why an Overview?

The API overview tells potential users the things they might want to know before adoption. There are people need to size up your product in order to decide whether they want to use it. They are either the managers responsible for a business decision, or they are engineers who need to know enough about your product to determine whether it can accomplish what they want it to do. Any of these people might decide not to adopt your product unless you provide an overview that answers their questions.

Content of Your Overview

Try to anticipate the questions that potential users will have about your product. Here are some general questions that are often applicable.

  • Are there any knowledge prerequisites?

  • What is it supposed to do? (What problem does it solve, and for whom)

  • What exact capabilities are available to the user? What services does it offer?

  • What does it NOT do that developers should know about?

  • What are the typical use cases? (Who is using it to do what?)

  • How much work is it to implement the solution?

  • How does it work? (Do users need to know about architecture of internal components? Do they need to know about open source platforms it is built on top of? Is it extensible?)

  • High level workflow. Describe the process, but not in too much detail. Subsequent chapters will cover the step-by-step actions for each part of the workflow.

  • Where to find documentation and other resources that are available.

Your users might have other questions that are specific to your product or to the industry you serve. The overview is a good place to enlist field engineers and Product Managers for additional perspective.

Overview Examples