Permalink
Switch branches/tags
Nothing to show
Find file Copy path
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