Documenting your SashiDo Applications with GitHub

Alexander V. Ruptsov

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:

  1. By using a README file - this is a simple way to inform others about your project.
  2. 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.

createREADMEwithRepo

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.

createREADMEafterRepo

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:

  1. 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.
  2. 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.
  3. 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.
  4. Usage - After you've told users how to install your project locally, you can include brief instructions on how to use it.
  5. 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.
  6. 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.

createWiki

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.

editWiki

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.

addingWikiPage

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:

codeBlock

Renders to this syntax highlighted code sample:

renderedCodeBlock

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

Happy documenting :)

Alexander V. Ruptsov

Customer Success Superstar @ SashiDo.

Find answers to all your questions

Our Frequently Asked Questions section is here to help.







Latests news

How to make your Mobile Application GDPR Ready

At SashiDo we certainly care about our customers and we strive to be up-to-date on the horizon of the novelties coming up. We’re all working on GDPR these days and we want to help people understand what it is. What does GDPR mean? In February we announced that GDPR is coming and SashiDo.io is getting ready and now we will be more specific on how to make sure your mobile app is prepared for the upcoming changes in the European Union region.

Read More

SashiDo Acquires Octobas

SashiDo is pleased to announce its recent acquisition of all the assets of Octobas.com, a robust and scalable backend for mobile and web apps based on Parse Open Source. For the past 2 years our mission has been to become a leading Parse Server hosting provider in the mobile and web apps development world as well as to continue improving our service, launching new features and providing quality and security to our customers.

Read More