A README file is probably the most important part of any documentation. It is the first contact anyone should have with your code, and it should be clean and structured so even a final user could understand it. If you are writing the readme for your code you shoul consider adding these points:

  • Name and version: How do you call your project?
  • Description: What does it do?
  • Features: What is special about your solution?
  • Example: Can I see it working? Where?
  • Requirements: What do you need to do before it runs?
  • Install: How do I get it for myself?
  • Configuration: What settings should I check for before or once it’s running?
  • Instructions: How do I get around? Do you have a wiki?
  • Uninstall: If your program gets installed on my system, can I uninstall it once I’m done with it?
  • Files: Are there any important files I have to be attentive about?
  • Issues: Known bugs and where to report them. If you use github, you can use it’s own issue tracking system.
  • Change log: How has your project changed along the way
  • Contribute: How can anyone help improve this project? This is very important for community projects.
  • Credit: acknowledgments and credits
  • Contact: Who is in charge of the project?
  • Copyright: It’s always a good idea to add a license to the project.

Not all of these points will always be necessary, but it’s a good reference. This is also a good starting point for RDD.