1. Creating a README
Fantastic work. We’ve created a repo! We’re now going to focus on the README file, reviewing how to edit it and what it should include.
2. Edit the README
We are in the default view of a repo, which is the Code section.
3. Edit the README
Regardless of the number of files we have, the README will always show after the list of files. It is a markdown file, as seen with the dot-md extension.
4. Edit the README
As we scroll down, we see a pencil icon in the top-right corner of the README rendering. Clicking on this will open the file for editing.
5. Markdown
The view of the README file will change to show the markdown syntax.
6. Edit vs. Preview
We can toggle between the Edit and Preview views to see if we have used the markdown syntax correctly. Let’s look at some fundamentals of markdown syntax we’ll likely need to use regularly.
7. Headings
First, we’ll look at headings. We can add headings by including one or several hashtags together. One hashtag is the biggest title heading available,
8. Headings
down to six hashtags stringed together, which is the smallest available in markdown.
9. Headings
Note that specific headers also add a line to the file.
10. Text formatting
We can make our text italic or bold by adding one or two asterisks on either side of our text.
11. Hyperlinks
We can include hyperlinks with the use of square brackets and parentheses. The square brackets will contain the text we want to be visible and clickable, while the parentheses will contain the desired URL.
12. Hyperlinks
This renders the link clickable in the preview tab and the file.
13. Images
Images use a similar format to the hyperlinks but with an added exclamation mark at the front. The text in the square brackets is alternative text, which is the text that appears in place of an image if it fails to load and is used by screen readers. It is important for accessibility. We can drag and drop an image, and GitHub will automatically render the code.
14. Writing a README
Now that we know how to style our README, let’s look at what it should include. README files need to be descriptive to allow anyone to understand our project, the contents of our repository, and how to use it. It is the first file a person will see, and as a data professional, it is a crucial skill to communicate a project to others. Consider it to be the instruction manual for our repository.
15. README fundamentals
Some essential items are the project title, a description of the technology used and why, a description of the process used to answer the question and why, and a table of contents.
16. README extras
Other characteristics of a good README are if it includes details of how the project came about and the motivation behind it, any limitations or challenges encountered, a recap of the problem it intends to solve, and what its intended use is. If we are sourcing information from elsewhere, it’s also essential to include the necessary credits.
17. Let's practice!
Let’s try to make a descriptive README for our soccer analysis project.