Documenting Your Project on Github

By | October 11, 2022

Mangihin.com is a website that provides useful information, please share if there is interesting information that can help you. Thank you

Documenting Your Project on Github – Accessible documentation allows people to learn about a project, making it easy to update ensuring that documentation remains relevant.

Two common ways to document a project are README files and wikis

  1. README files are a quick and simple way for other users to learn more about your work.
  2. The wiki on Github helps you present in-depth information about your project in a useful way.

It’s a good idea to at least have a README in your project, because that’s the first thing a lot of people will read when they first find your project.

Create README

When you create a new repository via GitHub, select “Initialize this repository with README” unless you plan to import an existing repository.

Documenting Your Project on Github

Your README.md file is now available for editing in your new repository. Your project name is at the top, followed by whatever description you chose to include when creating the repository. The README is easy to modify, either on Github or locally. Check out the Markdown mastering guide to learn more about modifying the text in a file once you’ve created it.

README format

READMEs generally follow one format to quickly direct developers to the most important aspects of your project.

  • The project name: Your project name is the first thing people will see when they scroll to your README, and is included when creating your README file.
  • Description: Here is your project description. Good description Clear, concise, and to the point. Explain the importance of your project and what it does.
  • List of contents: Optionally include a table of contents so others can quickly navigate a long or detailed README.
  • Installation: Installation is the next section in an effective README. Tell other users how to install your project locally. Optionally, include a gif to make the process clearer to others.
  • Usage: The next section is usage, where you teach other people how to use your project after they install it. This would also be a good place to include screenshots of your project.
  • Credits: Include a credits section to highlight and link to the author of your project.
  • License: Lastly, Include sections for your project license like MIT license etc. For more information on choosing a license, see the Github licensing guide

Your README contains only the information necessary for developers to start using and contributing to your project. Longer documentation is best suited for wikis, as described below.

Create a wiki

Every repository on Github comes with a wiki. After creating the repository, you can manage the included wikis via the navigation bar. Starting your wiki clicks the wiki button and creates your first page.

Documenting Your Project on Github

Adding Content

Wiki content is designed to be easy to edit. You can add or change content on any wiki page by clicking the edit button located at the top right corner of each page. open the editor on the wiki.

Documenting Your Project on Github

Wiki pages can be written in any format supported by Github Markup. Using the drop-down menu in the editor, you can choose the format of your wiki, and then use the toolbar to create and insert content on the page. The wiki also gives you the option to include custom footnotes where you can list things like box details or licensing information for your project.

Github keeps track of changes made to every page on your wiki. Under the page title, you can see who made the most recent edits, in addition to the number of commits made to the page. Clicking on this information will take you to a full page history where you can compare revisions or view a detailed list of edits over time.

Add Page

You can add additional pages to your wiki by selecting New Page in the upper right corner. By default, every page you create is automatically included in your wiki sidebar and listed in alphabetical order.

Documenting Your Project on Github

Support

You can also add a custom sidebar to your wiki by clicking the Add a custom sidebar link, sidebar custom content can include text, images, and links.

Note: The page called “Home” serves as the login page for your wiki. If it doesn’t exist, an automatically generated table of contents will be displayed instead.

Syntax Highlighting

Wiki pages support automatic code syntax highlighting for multiple languages ​​using the following syntax:


```ruby
   deff foo
     puts `bar`
   end
```

The block must start with three backticks, optionally followed by the name of the language the block contains. See pygments for a list of syntax highlightable languages.

The block content must be indented at the same level as the opening backticks. The block must end with three backticks that are indented at the same level as the opening backtick.

Done

You’ve learned some important information on how to best share your project with the rest of the Github community, Good luck.

Thanks for reading Documenting Your Project on Github. May be useful!