|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).
On GitHub, if a Git repository has a README file in its main (top-level) directory, it is automatically converted into formatted HTML and presented on the main web page. Various different file extensions can be used, and conversion to HTML takes account of the file extension of the file – for example, a "README.md" would be treated as a GitHub-flavored Markdown file.
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.
- Preston-Werner, Tom (23 Aug 2010). "Readme Driven Development". Tom Preston-Werner's personal blog. Retrieved 30 July 2014.
- 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.
- "Markup". GitHub. GitHub. 25 December 2014. Retrieved 8 February 2015.
- This article is based in part on the Jargon File, which is in the public domain.