GitHub is Your Documentation Landing Page

A presentation at DevRelCon London in December 2019 in London, UK by Lorna Jane Mitchell

Slide 1

Slide 1

GitHub is your Documentation Landing Page Lorna Mitchell, Nexmo

Slide 2

Slide 2

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

Slide 3

Slide 3

YOU ARE HERE @lornajane

Slide 4

Slide 4

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

Slide 5

Slide 5

README and GitHub Client Library for PHP ============================ [![Build Status](https://api.travis-ci.org/Nexmo/nexmo-php.svg?branch=mas [Latest Stable Version]( [MIT licensed](./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

Slide 6

Slide 6

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

Slide 7

Slide 7

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

Slide 8

Slide 8

Begin a README • 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 @lornajane

Slide 9

Slide 9

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

Slide 10

Slide 10

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

Slide 11

Slide 11

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

Slide 12

Slide 12

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

Slide 13

Slide 13

README Extra Info Include this for all project types, usually at the end • How to get help (an issue, an email?) • Links to related resources or further reading @lornajane

Slide 14

Slide 14

Beyond the README @lornajane

Slide 15

Slide 15

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

Slide 16

Slide 16

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

Slide 17

Slide 17

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

Slide 18

Slide 18

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

Slide 19

Slide 19

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