Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Latest commit

 

History

History
43 lines (27 loc) · 2.44 KB

about-overview.md

File metadata and controls

43 lines (27 loc) · 2.44 KB
Raw

The overview

When do I need an overview

Your API documentation should include an overview document. This document tells potential users or buyers what they might want to know before they buy.

Users can install or connect to your service if they are already familiar with it, or if someone else has decided that the team will use this solution. Those readers will go to your Quick Start Guide, or get straight to work.

Other readers need to assess your product to decide whether they want to use it. This includes managers responsible for a business decision, or engineers responsible for a technical assessment of your product. People in these groups might decide to not adopt your product unless you provide an overview that answers their questions.

Content of your overview

Who is this overview for

  • Are you writing for developers or for managers?
  • Are you writing for people who have a certain problem to solve?
  • Are you writing for a particular industry or market segment?

Body of the overview

Contains information that helps the reader get oriented to the API. Answers these questions:

  • 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?
  • How does it work? (What do users need to know about architecture an internal components?)
  • What dependencies does the developer need to know about before installing?
  • What technical requirements do readers need? Include development environment and licensing requirements.
  • What knowledge prerequisites does the developer need to know about before using the API?

Post-requisites

  • What comes next? Do you want to direct users to the Quick Start to try it out?
  • How to get started with the API?

More information

Overview examples

  • Chrome Native Client. The Native Client Technical Overview explains an engine that allows C++ to run in the browser, including why it's a good solution for engineers who want to rework a desktop app and make it usable as a web app.

  • The Jira Platform. This overview of the Jira Platform does a good job of explaining products and the associated use cases, third-party integrations, hosting options, and licensing.