A presentation at APItheDocs in in Amsterdam, Netherlands by Lorna Jane Mitchell
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 ============================ [
](./LI [ @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
Having a good README file in every GitHub project is a key ingredient of good developer experience, but what makes a good README? This session looks at the various types of projects you might want to create a README for, and offers examples of good README practice in each case. Making sure the purpose and status of the project is key, and directing users to your (beautiful and actively maintained) main documentation is definitely part of the deal. But we can do more to engage and inform developers that reach our projects this way, and this session will show you how. Recommended for everyone who wants to make the projects we create a welcoming place for users, however they find us.
The following resources were mentioned during the presentation or are useful additional information.
Here is where we keep our templates and checklists for setting up good github repositories
Here’s what was said about this presentation on social media.
