This article has multiple issues. Please help improve it or discuss these issues on the talk page. (Learn how and when to remove these template messages)(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
README.md (for a text file using markdown markup),
README.1ST – or simply
The file's name is generally written in uppercase letters. On Unix-like systems in particular this makes it easily noticed – both because lowercase filenames are more usual, and because traditionally the ls command sorts and displays files in ASCIIbetical ordering, so that uppercase filenames appear first.[nb 1]
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)
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.
In more recent times, the popular GitHub proprietary Git repository strongly encourages a README file - if one is included in the main (top-level) directory, it is automatically presented on the main web page. While traditional plain text is supported, various different file extensions and formats are also supported, and conversion to HTML takes account of the file extension of the file – in particular a "README.md" file would be treated as a GitHub Flavored Markdown file.
As a generic termEdit
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:
A detailed changelog, intended for programmers
A basic changelog, intended for users
Copyright and licensing information
Known bugs and instructions on reporting new ones
Guide for prospective contributors to the project
- This is often no longer the case – but LC_ALL=C ls will show the older behavior.
- Raymond, Eric Steven (1996). The New Hacker's Dictionary. MIT Press. pp. 378–79. ISBN 978-0-26268092-9.
- Manes, Stephen (November 1996). "README? Sure--before I buy!". PC World. 14 (11): 366.
- "DECUS 10-LIB-4 Contains 10-210 through 10-241, except 10-223". pdp-10.trailing-edge.com. Retrieved 3 March 2018.
- "PDP-10 Archive: decus/20-0079/readme.txt from decus_20tap3_198111". pdp-10.trailing-edge.com. Retrieved 3 March 2018.
- "GNU Coding Standards: Releases". www.gnu.org. Retrieved 3 March 2018.
- "Code-sharing site Github turns five and hits 3.5 million users, 6 million repositories". TheNextWeb.com. 11 April 2013. Retrieved 11 April 2013.
- "Markup". GitHub. GitHub. 25 December 2014. Retrieved 8 February 2015.
- Johnson, Mark (1 February 1997). "Building a Better ReadMe". Technical Communication. Society for Technical Communication. 44 (1): 28–36. JSTOR 43089849. 
- Rescigno, Jeanne (August 1997). "Hypertext good choice for README files". Technical Communication. Society for Technical Communication. 44 (3): 214. JSTOR 43089876.
- Livingston, Brian (14 September 1998). "Check your Readme files to avoid common Windows problems". InfoWorld. Vol. 20 no. 37. InfoWorld Media Group, Inc. p. 34. Archived from the original on 18 November 2006. Retrieved 4 June 2019. 
- Benjamin, Andrew (15 September 1996) . Written at Department of Philosophy, University of Warwick, UK. Guédon, Jean-Claude (ed.). "Readme: Writing Notes - Meditations on the temporality of writing". Surfaces (Electronic journal) (in English and French). Université de Montréal, Montreal (Quebec), Canada: Les Presses de l'Université de Montréal. III (12): 1–12. ISSN 1188-2492. Archived from the original on 20 February 2006. Retrieved 4 June 2019. 
This article is based in part on the Jargon File, which is in the public domain.