Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
79 lines (46 sloc) 2.63 KB

What is this repository?

As you might have realised MailFace is not a real product. This repository is an example repository that tries to show how to write a good copy for an SDK on Github.

Goals

The goal of repo documentation is:

  • For a developer to install and initialize the SDK library
  • For a developer to make their first SDK/API call
  • For a developer to know where to find their API credentials
  • For a developer to know where to get support
  • For a developer to know where to find further documentation

The goal of repo documentation is not:

  • To be the main source for documentation on the API and SDKs. For full documentation the user should be sent to the docs on the main developer documentation portal
  • To document API arguments and response codes. Again, this is what the developer documentation on the docs site is for,

Content

The parts that make up good copy for a repository are (from top to bottom):

In the repo header

  • A short and descriptive repo title
  • A link to the docs for this language in the title

In the README

  • A short and descriptive title
  • A badge showing the current library version
  • A badge showing the current build status of the master branch
  • A link (badge or regular) to support channels
  • A short descrition of what the product does.
  • A link to the product's homepage and language specific docs.
  • An Installation section
    • Which shows how to install the library
    • Which lists any requirements on the language or platform
    • Which then links out to the official docs to continue
  • A Get Started section
    • That instructs a user where to register and get their API credentials (and potentially set up their first app)
    • That shows a code sample that demonstrates how to initialize the library
    • That shows a code sample that demonstrates how to make a first SDK call with the library
    • Which then links out to the official docs to continue
  • An Initialization section
    • That shows an overview of the different ways the library can be initialised
    • That reminds the user where to get their API credentials or sign up
    • Which then links out to the official docs to continue
  • A Documentation section
    • That links out to the Get Started docs for this language, and a few sample use cases
    • That links out to the Reference docs for users looking to get info on SDK call arguments and responses
  • A Contributing section
    • That links to the contributor guidelines
  • A License section
    • That summarizes and links to the license file
  • A __Help_ section
    • That summarizes the various places to get support