Why should I be writing better READMEs?


First, let's answer the question: What is a README?

A README file contains information about other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called 
READ.ME
, 
README.TXT
, 
README.md
(for a text file using markdown markup), 
README.1ST
– or simply 
README
.
— Wikipedia

Boiled down, a README is the document that contains everything about your project.

READMEs are written by nearly every single tech company. See for yourself:



There is, however, one problem with READMEs. They are often disorganized, vague, and hard to follow. There is no universal standard or guideline that everyone follows to create a README.

This lack of consistent documentation greatly hinders the development process.

By writing better READMEs, you can improve the channel of communication in which developers share ideas. By streamlining and standardizing the process of writing a README, stereotypical and semantic noise can be eliminated.

By adding references and following a universal outline, the effectiveness and flow of any README can be improved.

Here's a good list of what READMEs generally contain. This can serve as an outline.

General README Outline

  • About the project
  • Installation instructions
  • Configuration instructions
  • Operating instructions
  • Troubleshooting instructions
  • Changelog
  • Licence

To create better READMEs, simply think about your audience. How do you think they will interpret your documentation? It's up to you to improve the channel of communication.

To get started, click   Create  or check out some good resources.

The sources used for this project can be found below.

Sources

  1. “Gnu.org.” Free Software Foundation, www.gnu.org.
  2. Johnson, Mark. Building a Better ReadMe. 1997.
  3. HotFrameworks. Web Framework Rankings | HotFrameworks, hotframeworks.com.
  4. PurpleBooth. “A Template to Make Good README.md.” GitHub, gist.github.com/PurpleBooth/109311bb0361f32d87a2.
  5. Thompson , Caleb. “How To Write A Great README.” ThoughtBot, robots.thoughtbot.com/how-to-write-a-great-readme.
  6. Examples of Good README Files, courses.cs.washington.edu/courses/cse326/02wi/homework/hw5/good-readmes.html.
  7. Jabiinfante. “Art of README.” GitHub, 23 Mar. 2017. https://github.com/noffle/art-of-readme
  8. Nimare, Akash. “A Beginners Guide to writing a Kickass README ✍ – Akash Nimare” Medium.com, Medium Inc., 25 Nov. 2016, medium.com/@meakaakka/a-beginners-guide-to-writing-a-kickass-readme-7ac01da88ab3.
  9. Koberger, Gregory. “ReadMe.io.” ReadMe, readme.io
  10. Bodimer, Shane F, and Patrick Taylor. “Research and Interpreting Documentation.”
  11. Klutznick, Philip M. Computer Science and Technology: Computer Model Documentation Guide. 73rd ed., vol. 500, ser. 80-600190, Washington, National Bureau of Standards, 1981. https://www.gpo.gov/fdsys/pkg/GOVPUB-C13-241fb5e2d1e825f2c6ebd3555a76cc90/pdf/GOVPUB-C13-241fb5e2d1e825f2c6ebd3555a76cc90.pdf
  12. Zobel, Justin. Writing for Computer Science. 3rd ed., London, Springer, 2014. http://www.cse.chalmers.se/edu/year/2015/course/DAT147/Zobel%20-%20Writing%20for%20computer%20science%203rd%20edition.pdf
My class presentation: ppt-readme.pdf
Create README