Whether you're starting a completely new software project or wanting to take a "Docs as Code" approach with your documentation on GitHub, one of the first steps is creating a repository (repo). Here's how it's done.
Why Create a GitHub Repo?
Git is an open-source distributed revision control system that allows multiple developers (and writers!) to constantly and consecutively make and track changes to code or documentation in a centralized location without overriding someone else's work. This version control makes it so that if something breaks, you can easily hunt down the source of the problem and revert back to a working version before the problematic code is pushed.
It's also good for tracking who contributed to what and when. This is especially important when multiple people from different time zones are contributing to one project.
By creating a GitHub repo, you bring these benefits to your project. Additionally, if you allow your repo to be open to the public, others can contribute---whether that involves fixing broken code or even making corrections to typos. You may even be able to release a working beta version ahead of schedule. Open source is a beautiful thing.
How to Create a GitHub Repo
To set up a project on GitHub, you'll need to create a repo. To do so, log in to (or create) your GitHub account. Once logged in, click the "+" icon on the right side of the header menu (which is accessible from anywhere on the site). Select "New Repository" in the drop-down menu that appears.
You'll now be on the "Create a New Repository" page. Choose the owner of the repo and give it a short, memorable name. Keep in mind that the name of the repo needs to be URL-friendly. While there is no strict convention, the most popular way is to use all lowercase letters while separating words with a hyphen, such as
example-repo-name
. If you use spaces in the name, a hyphen will be added in its place.
Once you've named your repo, give it a brief description and choose whether you want to make the repo public or private.
Next, you can:
- Add a README file: Introduce and explain how to use and contribute to your project.
- Add .gitignore: Choose which files to ignore.
- Choose a license: Let others know what they can and can't do with your project's code.
These are optional but highly recommended to add. When you're ready, click "Create Repository."
Your repo is now created.
Once you've created a repo, you can clone it to your local machine, which allows you to make edits to the content locally rather than directly to the source files in the repo.