Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

GitHub as a Landing Page

18 views

Published on

You can write the best, most structured documentation in the world - and your users will still arrive by some other route. This session focuses on the GitHub repos that your documentation references, and how to prepare for these to be the entry point for someone.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

GitHub as a Landing Page

  1. 1. GitHub is your Documentation Landing Page   Lorna Mitchell, Nexmo
  2. 2. Landing Pages The homepage of your documentation   A finely crafted experience   @lornajane
  3. 3. YOU ARE HERE @lornajane
  4. 4. Repository Standards   https://github.com/Nexmo/repo-standards @lornajane
  5. 5. README and GitHub Client Library for PHP ============================ [![Build Status](https://api.travis-ci.org/Nexmo/nexmo-php.svg?branch=mas [![Latest Stable Version](https://poser.pugx.org/nexmo/client/v/stable)]( [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./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
  6. 6. README and GitHub GitHub renders documentation on the main repo page @lornajane
  7. 7. README and GitHub Package managers use README too (e.g. https://packagist.com) @lornajane
  8. 8. 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
  9. 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
  10. 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
  11. 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
  12. 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
  13. 13. README Furniture Use headings and a table of contents to help users navigate longer READMEs   @lornajane
  14. 14. Beyond the README @lornajane
  15. 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
  16. 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
  17. 17. Welcome Participation Help users to participate • CODE_OF_CONDUCT.md • CONTRIBUTING.md @lornajane
  18. 18. GitHub is Your Landing Page Welcome and orient your user, however they reached you.   @lornajane
  19. 19. 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

×