GitHub is Your Landing Page

GitHub is your Documentation Landing Page Lorna Mitchell, Nexmo

Landing Pages The homepage of your documentation A finely crafted experience @lornajane

YOU ARE HERE @lornajane

Repository Standards https://github.com/Nexmo/repo-standards @lornajane

README and GitHub Client Library for PHP ============================ [![Build Status](https://api.travis-ci.org/Nexmo/nexmo-php.svg?branch=mas []( [](./LI [![codecov](https://codecov.io/gh/Nexmo/nexmo-php/branch/master/graph/bad This library requires a minimum PHP version of 7.1 This is the PHP client library for use Nexmo’s API. To use this, you’ll n nexmo.com][signup]. @lornajane

README and GitHub GitHub renders documentation on the main repo page @lornajane

README and GitHub Package managers use README too (e.g. https://packagist.com) @lornajane

README Basics • Project title and short explanation of its purpose and scope • Link to documentation or other source link for this project • A bit about Nexmo, including a signup link • … the middle section depends on your project type … • How to get help (an issue, an email?) • Links to related resources or further reading @lornajane

Repo Types We’re working on three distinct types of repository: • Library Code • Tool or Demo App • Supporting Code … docs-as-code is probably a fourth category @lornajane

Library Code README Try these ingredients for a good library README recipe: • Pre-requisites, such as technology requirements, Nexmo account • Installation instructions • Usage instructions • the API reference is not enough by itself • every project needs lots of examples @lornajane

Installable Item README For Apps/Demos, use the Library recipe, with extra ingredients • Pre-requisites, such as technology requirements, Nexmo account • Installation instructions • Usage instructions • Deployment instructions • a docker setup • “click to deploy” e.g. Heroku @lornajane

Supporting Code README If the code was really just shared to accompany something else: • Link to the thing it is for … anything else is a bonus :) @lornajane

README Furniture Use headings and a table of contents to help users navigate longer READMEs @lornajane

Beyond the README @lornajane

Repo Metadata Give your project a clear name! • Description is key because it shows in search results • Use the topics to help indicate both technology and features @lornajane

Give Permission Every project needs a LICENSE.md without which nobody can use your project anyway Use a standard (OSI) and make sure GitHub has recognised it. @lornajane

Welcome Participation Help users to participate • CODE_OF_CONDUCT.md • CONTRIBUTING.md @lornajane

GitHub is Your Landing Page Welcome and orient your user, however they reached you. @lornajane

Resources and Further Reading • https://github.com/nexmo • https://lornajane.net • https://stoplight.io/blog/open-source-documentation/ • https://github.com/ekalinin/github-markdown-toc.go • https://opensource.org/licenses @lornajane