If you’ve never used markdown before, don’t be intimidated. You can also use it to create colorful pull request comments, and even in commit messages. Markdown works on GitHub with any file that has. Think of it as styles file for a webpage, only without the pesky HTML and CSS. Plainly put, it’s a bunch of hash signs and other symbols you use with text to make things bigger or bolder or otherwise change their appearance. This is a GitHub-specific markdown language, as in a lightweight text-based syntax for formatting text.
Here is a guide to (1) how you might maybe format it and (2) how to do that formatting with GitHub Flavored Markdown. So above is the info you need to include.
Using Markdown to Make Your README Look Professional Here is a list of what a typical README will contain:Īfter that, you might consider including some of these other helpful sections: Now fill in the rest by telling us about This Thing I Made, ‘k?) If you are having trouble getting started writing a README, here is a sentence prompt: “My project is…”. On the other hand, every single one starts the same way: WHAT YOUR PROJECT DOES.
So there is no one set way of writing a README that works for all repos.
What, then, are the elements of a great README?Įvery one of the 27 million public repositories on GitHub represents a project, from entire JavaScript frameworks to tiny single-function software packages somebody, somewhere, thought might be useful. Because, um, you failed to tell us what it even IS? Writing a Great README Don’t be That Guy who clearly works really really hard creating an open source project, puts it up on GitHub with no README whatsoever… and then sits there wondering why nobody is forking their project. Until you’ve written about your software, you have no idea what you’ll be coding. Writing a Readme is absolutely essential to writing good software. I know, I know, we’re programmers, dammit, not tech writers! But that’s where you’re wrong.
As in, before you write any code or tests or behaviors or stories or ANYTHING. How bad? Well, Tom Preston-Werner, one of the founders of GitHub, wrote a compelling essay about README Driven Development: “The Readme should be the single most important document in your codebase writing it first is the proper thing to do…įirst. In fact, it’s really bad to skimp on your README. This is understandable software development is a fast-flowing river, and it’s super hard to paddle back upstream to revisit any code that is not a problem/bug/actively on fire. We’ve all done it, every one of us with the intent to come back later and do it right.
Too many developers, however, either skip the README entirely, or put some generic boilerplate text in. It’s the first way most people who come to your repo will interface with your project, and it’s so important that GitHub includes README creation prompts in the repository setup workflow: The README is like the public face of your work.
Directly below the list of project files is where you find the README. What is a README.md, exactly, in GitHub land? When you visit any repository on GitHub, the first thing you see is the file tree - which, for massive open source projects like the Linux kernel, can be dozens of lines long. Hail, fellow Git pilgrims! As we wind down our tutorial series on learning Git and GitHub from your first git init to your most recent pull request, we now pause to consider the humble, often overlooked, README.md file.