README

From Wikipedia, the free encyclopedia
Jump to: navigation, search
Not to be confused with Reamde, a novel by Neal Stephenson.
The README file for cURL

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.[1]

Contents[edit]

The contents typically include one or more of the following:

History[edit]

It is unclear when the convention began, but there are examples dating back to the mid 1970s.[3][4]

A README file is a requirement in the GNU Coding Standards[5] 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[edit]

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,[6] 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[edit]

The expression "readme file" is also sometimes used generically, for files with a similar purpose.[citation needed] 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

Other files commonly distributed with software include a FAQ and a TODO file listing possible future changes.

Further reading[edit]

  • 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. 

References[edit]

  1. ^ Note that this is often no longer the case – but LC_ALL=C ls will show the older behavior.
  2. ^ a b Manes, Stephen (November 1996). "README? Sure--before I buy!". PC World. 14 (11): 366. 
  3. ^ http://pdp-10.trailing-edge.com/decuslib10-04/index.html
  4. ^ http://pdp-10.trailing-edge.com/decus_20tap3_198111/01/decus/20-0079/readme.txt.html
  5. ^ [1]
  6. ^ "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.