A crucial step for a successful project is documentation. When you present documentation in your project, it's easier for people to get to know what your project's about. But don't forget to update it from time to time so it stays relevant and useful.
Fortunately, GitHub makes the process of creating and maintaining documentation very easy.
There are two basic ways you can publish your documentation on GitHub:
- By using a README file - this is a simple way to inform others about your project.
- Using Wikis - they are used to present in-depth information.
Creating your README
At SashiDo, we automatically create a FREE Private repository for each application you make. Even better, each repo comes with a README containing useful information about how and where to set up some features. That being said, you can edit the README in any way you like.
Alternatively if you want to create your own repository, at the creation page, GitHub asks you whether you want it to come with a set of files in it, and the README is a part of them. You can tick it so the README file will automatically be created when you create the repo.
If you haven't selected the option described above, GitHub makes it even easier for you by letting you know that you can create a README so others can get familiar with your work.
Formatting your README
There are many formats that you might choose for your README. The best approach is to have a general, informative format. That way people can easily understand what your project is about and start working on it.
A sample format would be something like this:
- Project name - Who wouldn't include their project's name? GitHub even automatically adds your project name to the beginning of the README! It's also included in the README that's created with your SashiDo app's repo.
- Description - What would a README be without a description? It should be clear and to the point, so it's easy for people to understand what your project is about.
- Installation - Your project may be awesome and fun, but if you do not include a brief guide on how to install it locally it might irritate some people.
- Usage - After you've told users how to install your project locally, you can include brief instructions on how to use it.
- Contribution - If your project is a big one, you may consider adding guidelines on how people can contribute to it. You can check out GitHub's guide for setting guidelines for repository contributors.
- Credits - It would be awesome if you emphasize and link to the project's creators and contributors.
If you want to have a longer, more in-depth documentation, Wikis are the way to go.
Creating a Wiki
Every repository on GitHub comes with a Wiki. To start using it, you only need to navigate to the Wiki tab in the toolbar and press the Create the first page button.
Adding Content
It's fairly easy to start editing the content of your Wiki. You just need to navigate to the Wiki, then press the Edit button.
The Wiki itself comes with an awesome editor. It's relatively easy and pleasant to use. It even lets you choose the type of format for your wiki, for example, GitHub Markdown, but you can use any format supported by GitHub Markup. This can be done in the drop menu in the editor. There's even a preview feature, which lets you see the formatted content. You can check it out by pressing on the Preview tab, right next to Write.
When you've added all the content you want, before you save it, you can add an Edit Message, notifying what and why you added/edited. GitHub automatically creates a transparent history of who and what people edited, added or deleted on each page. You can find information about the last person who committed to the given page right below the title. If you want a detailed history of the changes, you can click on that information and a page with the full history will be displayed.
Another awesome feature that the Wiki offers is that you can add a custom footer, in which you can store any contact details or license information regarding your project.
Adding Pages
Of course, one page will not be enough for an in-depth documentation. To add a new page to your Wiki, go to the upper-right corner and click on the New Page button.
Every page you create is automatically added to the sidebar in alphabetical order so you can navigate pages easily.
If that's not enough, you can even create your own custom sidebar. It's located right under the Pages list.
An important thing to know is that the Home page serves as the main page of your Wiki and should it be missing, some automatically generated content will be displayed at its place.
Syntax highlighting
Another awesome feature of the Wiki is that it supports syntax highlighting of code. If you want to check all the supported languages you can check them here.
To utilize the syntax, the code block must start with three backticks and you can specify the name of the language the block will contain, but it's optional. After you've inserted the code, the block must end with another three backticks at the same indent level as the first three.
Here's an example with JavaScript:
The following code block:
Renders to this syntax highlighted code sample:
You're ready to go!
You have adapted some vital information about how to best document and present your project on GitHub, regardless of whether your project is big in scope and requires a Wiki, or you're simply beginning and setting up a reasonable and compact README.
Few beautiful wikis and readmes examples
- https://github.com/krasimir/kuker/blob/master/README.md
- https://github.com/NYTimes/objective-c-style-guide
- https://github.com/parse-community/parse-server/wiki
- https://github.com/krasimir/react-in-patterns/blob/master/README.md
- https://github.com/guardian/frontend/wiki
- https://github.com/airbnb/react-with-styles/blob/master/README.md
Happy documenting :)
Germany
Bulgaria
