|This article needs additional citations for verification. (April 2009) (Learn how and when to remove this template message)|
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.
The file's name is generally always written in upper case. On Unix-like systems in particular this makes it easily noticed – both because lower case filenames are more usual, and because traditionally the ls command sorts and displays files in ASCIIbetical ordering, so that upper-case filenames appear first.
The contents typically include one or more of the following:
- Configuration instructions
- Installation instructions
- Operating instructions
- A file manifest (list of files included)
- Copyright and licensing information
- Contact information for the distributor or programmer
- Known bugs
- Credits and acknowledgments
- A changelog (usually for programmers)
- A news section (usually for users)
|This section needs expansion. You can help by adding to it. (February 2015)|
A README file is a requirement in the GNU Coding Standards. Since the advent of the web as a de facto standard platform for software distribution, many software packages have moved (or occasionally, copied) some of the above ancillary files and pieces of information to a website or wiki, sometimes including the README itself, or sometimes leaving behind only a brief README file without all of the information required by a new user of the software. However, the popularity of GitHub (as well as older community conventions) has contributed towards README files still being widely used in open-source software (see next section).
As a generic term
The expression "readme file" is also sometimes used generically, for files with a similar purpose. For example, the source code distributions of many free software packages, especially those following the Gnits Standards or those produced with GNU Autotools, include a standard set of readme files:
README General information AUTHORS Credits THANKS Acknowledgments CHANGELOG A detailed changelog, intended for programmers NEWS A basic changelog, intended for users INSTALL Installation instructions COPYING / LICENSE Copyright and licensing information BUGS Known bugs and instructions on reporting new ones
- Johnson, Mark (February 1997). "Building a Better ReadMe". Technical Communication. Society for Technical Communication. 44 (1): 28–36.
- Livingston, Brian (14 September 1998). "Check your Readme files to avoid common Windows problems". InfoWorld. Vol. 20 no. 37. p. 34.
- Note that this is often no longer the case – but LC_ALL=C ls will show the older behavior.
- Manes, Stephen (November 1996). "README? Sure--before I buy!". PC World. 14 (11): 366.
- This article is based in part on the Jargon File, which is in the public domain.