Skip to content

Latest commit

 

History

History
 
 

WritingREADMEs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Markdown.md
Markdown.md
 
 
README.md
README.md
 
 

README.md

README Quick Reference Guide

  • This is by no means an all-inclusive list of everything you should have in your README.
  • READMEs can be written in Markdown(.md) or as a text file (.txt).

Program Overview

  • Give a brief description of what your project is and what it is intended to do.
  • Include an example of what your project can do, something that will grab the attention of someone who just happened upon your repository.

How to use

  • Provide the information required to effectively use your project.
  • You can, but are not required to, include example code.

Prerequisites

  • List any special or third party prerequisites needed to run your project (if your project requires a library that has to be installed on its own, it is a prerequisite).
  • If no unordinary prerequisites are needed this section is not necessary.
    • E.g. For a C++ project the SDL library would be a prerequisite but the vector library would not because it is included with the standard g++ installation.

Installation guide

  • List the steps needed to install your project.
  • It is better to explicitly list the commands needed rather than describe the steps.
    • E.g. make as opposed to "run make".

Bugs/Limitations/Issues

  • Explicitly list all of the known bugs in your project.
  • If there are any known limitations or issues, explicitly list those as well.
  • The more effective you are at conveying the nature of the bug/limitation/issue the better. This means being clear and concise in your wording and providing as much relevant information as possible.
    • E.g. "The foo function causes a segmentation fault when the argument passed in is negative" as opposed to "foo fails when the parameter is negative"

Things not to do

  • Do not include an authors and contributors section in your README, this information can be found elsewhere on Github.
  • There is no need to list the files in your repository in your README.
  • Avoid listing commands in words, instead explicitly list the commands using ` in sequential order.
  • It is not necessary to include information about your licensing beyond where to find it in your README.