GitHub as a Landing Page
0 likes260 views
The document outlines best practices for creating effective GitHub repositories, specifically for Nexmo's PHP client library. It emphasizes the importance of clear README files, repository types, and adequate documentation to guide users on installation, usage, and participation. Additionally, it highlights the necessity of including metadata, licensing, and resources for further reading.
](
[](./LI
[
GitHub as a Landing Page
- 1. GitHub is your Documentation Landing Page Lorna Mitchell, Nexmo
- 2. Landing Pages The homepage of your documentation A finely crafted experience @lornajane
- 5. README and GitHub Client Library for PHP ============================ []( [](./LI [ @lornajane
- 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. 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. 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. 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. 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. README Furniture Use headings and a table of contents to help users navigate longer READMEs @lornajane
- 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. 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. Welcome Participation Help users to participate • CODE_OF_CONDUCT.md • CONTRIBUTING.md @lornajane
- 18. GitHub is Your Landing Page Welcome and orient your user, however they reached you. @lornajane
- 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