Good documentation is key to the success of any project. Making documentation accessible enables people to learn about a project; making it easy to update ensures that documentation stays relevant.
Two common ways to document a project are README files and wikis:
GitHub readme.md closed Ask Question Asked 5 years, 6 months ago. Active 3 years, 11 months ago. Viewed 790 times -2. Digital Object Identifiers (DOI) are the backbone of the academic reference and metrics system. If you’re a researcher writing software, this guide will show you how to make the work you share on GitHub citable by archiving one of your GitHub repositories and assigning a DOI with the data archiving tool Zenodo. How to set up your profile, share with us, and get some inspiration from other great profiles. What will you showcase?As always, feel free to leave us a comm. Anyone with a GitHub account can create a README for their profile. All you have to do is create a new GitHub repository that has the same name as your username. Nmrpipe download. Then, add a README file and customize it accordingly. To add a GitHub Profile README to your account. GitHub renders the information provided by the app under the URL in the body or comment of an issue or pull request. To see content attachments, you must have a GitHub App that uses the Content Attachments API installed on the repository.
README files are a quick and simple way for other users to learn more about your work.
Wikis on GitHub help you present in-depth information about your project in a useful way.
It’s a good idea to at least have a README on your project, because it’s the first thing many people will read when they first find your work.
Creating your README
When you create a new repository though GitHub, select “Initialize this repository with a README” unless you plan to import an existing repository.
Your README.md file is now available for editing in your brand-new repository. Your project’s name is at the top, followed by any description you chose to include when creating the repository. READMEs are easy to modify, both on GitHub or locally. Check out the Mastering Markdown guide to learn more about how to modify the text within the file after you’ve made it.
Formatting your README
READMEs generally follow one format in order to immediately orient developers to the most important aspects of your project.
Project name: Your project’s name is the first thing people will see upon scrolling down to your README, and is included upon creation of your README file.
Description: A description of your project follows. A good description is clear, short, and to the point. Describe the importance of your project, and what it does.
Table of Contents: Optionally, include a table of contents in order to allow other people to quickly navigate especially long or detailed READMEs.
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 even more clear for other people.
Usage: The next section is usage, in which you instruct other people on how to use your project after they’ve installed it. This would also be a good place to include screenshots of your project in action.
Contributing: Larger projects often have sections on contributing to their project, in which contribution instructions are outlined. Sometimes, this is a separate file. If you have specific contribution preferences, explain them so that other developers know how to best contribute to your work. To learn more about how to help others contribute, check out the guide for setting guidelines for repository contributors.
Credits: Include a section for credits in order to highlight and link to the authors of your project.
License: Finally, include a section for the license of your project. For more information on choosing a license, check out GitHub’s licensing guide!
Your README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis, outlined below.
Creating your wiki
Every repository on GitHub comes with a wiki. After you’ve created a repository, you can set up the included wiki through the sidebar navigation. Starting your wiki is simply a matter of clicking the wiki button and creating your first page.
Adding content
Wiki content is designed to be easily editable. You can add or change content on any wiki page by clicking the Edit button located in the upper right corner of each page. This opens up the wiki editor.
Wiki pages can be written in any format supported by GitHub Markup. Using the drop-down menu in the editor, you can select the format of your wiki, and then use wiki toolbar to create and include content on a page. Wikis also give you the option of including a custom footer where you can list things like contact details or license information for your project.
GitHub keeps track of changes made to each page in your wiki. Below a 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 the full page history where you can compare revisions or see a detailed list of edits over time.
Adding pages
You can add additional pages to your wiki by selecting New Page in the upper right corner. By default, each page you create is included automatically in your wiki’s sidebar and listed in alphabetical order.
You can also add a custom sidebar to your wiki by clicking the Add custom sidebar link. Custom sidebar content can include text, images, and links.
Note: The page called “Home” functions as the entrance page to your wiki. If it is missing, an automatically generated table of contents will be shown instead.
If you're knowledgable with the command line, you can also modify wikis locally. Check out our help article for more info.
Syntax highlighting
Wiki pages support automatic syntax highlighting of code for a wide range of languages by using the following syntax:
The block must start with three backticks, optionally followed by the the name of the language that is contained by the block. See Pygments for the list of languages that can be syntax highlighted.
The block contents should be indented at the same level as the opening backticks. The block must end with three backticks indented at the same level as the opening backticks.
You’re done!
You have learned some important information about how to best share your work with the rest of the GitHub community, whether your project is large enough in scope for its own wiki or you’re just starting out and setting up a clear and concise README.
To read more on the topics covered in this article, our guides for creating a new repository, editing files in your repository, setting guidelines for repository contributors and choosing a license are great places to start. Otherwise, check out some other GitHub Guides to keep learning.
Finally, if you’re interested in building a documentation site for your project, we recommend using GitHub Pages.
Last updated July 15, 2016
Digital Object Identifiers (DOI) are the backbone of the academic reference and metrics system. If you’re a researcher writing software, this guide will show you how to make the work you share on GitHub citable by archiving one of your GitHub repositories and assigning a DOI with the data archiving tool Zenodo.
ProTip: This tutorial is aimed at researchers who want to cite GitHub repositories in academic literature. Provided you’ve already set up a GitHub repository, this tutorial can be completed without installing any special software. If you haven’t yet created a project on GitHub, start first by uploading your work to a repository.
Choose your repository
Repositories are the most basic element of GitHub. They’re easiest to imagine as your project’s folder. The first step in creating a DOI is to select the repository you want to archive in Zenodo. To do so, head over to your profile and click the Repositories tab.
Important! Make sure you tell people how they can reuse your work by including a license in your repository. If you don’t know which license is right for you, then take a look at choosealicense.com.
Login to Zenodo
Next, head over to Zenodo and click the Log in button at the top right of the page, which gives you an option to login with your GitHub account.
Zenodo will redirect you back to GitHub to ask for your permission to share your email address and the ability to configure webhooks on your repositories. Go ahead and click Authorize application to give Zenodo the permissions it needs.
Important! If you want to archive a repository that belongs to an organization on GitHub, you will need to make sure that the organization administrator has enabled third-party access to the Zenodo application.
Pick the repository you want to archive
At this point, you’ve authorized Zenodo to configure the repository webhooks needed to allow for archiving and DOI-issuing. To enable this functionality, simply click the On toggle button next to your repository (in this case My-Awesome-Science-Software).
Important! Zenodo can only access your public repositories so make sure the repository you want to archive is public.
Check repository settings
By enabling archiving in Zenodo, you have set up a new webhook on your repository. Click the settings tab on your repository, and then click ‘Webhooks’ in the left-hand menu. You should see something like the image below, which shows a new webhook configured to send messages to Zenodo.
Create a new release
By default, Zenodo takes an archive of your GitHub repository each time you create a new Release. To test this out, head back to the main repository view and click on the releases header item.
Unless you’ve created releases for this repository before, you will be asked to Create a new release. Go ahead and click this button and fill in the new release form.
Github Readme Profile
If this is the first release of your code then you should give it a version number of v1.0.0. Fill in any release notes and click the Publish release button.
Checking everything has worked
Creating a new release will trigger Zenodo into archiving your repository. You can confirm that this process took place by click the Upload tab in your Zenodo profile. You should see a new upload in the right-hand panel.
Minting a DOI
Before Zenodo can issue a DOI for your repository, you will need to provide some information about the GitHub repo that you’ve just archived.
Once you’re happy with the description of your software, click the Publish button at the bottom of the Zenodo form, and voilà, you’ve just made a new DOI for your GitHub repository!
Git Readme Template
Finishing up
Back on your Zenodo GitHub page you should now see your repository listed with a shiny new badge showing your new DOI!
ProTip: If you really want to show off, then right click on the gray and blue DOI image and copy the URL and place it in your README on your GitHub repo.
Last updated October, 2016