1. Writing a README.md File
The README.md file holds a special significance on GitHub. When you visit a repository’s home page, GitHub displays the contents of the README.md rendered as Markdown on the home page. The README.md contents is what visitors to your repository will expect to see to learn more about your project.
Chapter 3 includes information about what should be included in a README.md file. It should also include links to your CONTRIBUTING.md file and your CODE_OF_ CONDUCT.md file. After reading this file, a person should understand what your project does, how to get involved, and where to go to find out more information.
2. Writing Good Documentation
One of the most neglected aspects of open source is documentation. Writing good docs is a great way to distinguish your project from the rest. Also, documentation provides a nice way for others to dip their toes into open source. One of the authors got his start in open source by contributing docs to a project many, many years ago.
GitHub supports a wiki feature, but we recommend using a relatively unknown feature, serving a documentation site from the docs folder in the master branch of your repository. This feature has many benefits, but one of the big ones is the ability to version your documentation along with the code that it documents.
Chapter 4 walks through building a GitHub Pages site. Serving your documentation from the docs folder is very similar to that process. The following steps assume that you have a repository that is not a GitHub Pages website. Chapter 3 walks through creating a regular repository if you need a refresher.
Make sure to commit a file named index.md to the docs folder in the master branch of your repository. This feature requires that there’s already a docs folder before you can enable it. If you’re unclear about how to do that, Chapter 7 covers writing and committing code in detail.
Navigate to your repository settings and then scroll down to the GitHub Pages section. By default, the Source is set to None. Click the button and select the master branch /docs folder option as shown in Figure 10-10 and then click the Save button.
You can now visit your documentation site at https://{USERNAME}.github.io/ {REPO-NAME}/. To see an example of this in action, visit https://fakehaacked. github.io/best-example/.
As we cover in Chapter 4, you can select a theme and add a custom domain name if needed.
Don’t forget to add a link to the docs site to your README file so that people can find it.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.