README

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,[1] README.md (for a text file using markdown markup), README.1ST – or simply README.

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

Contents

The contents typically include one or more of the following:

History

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

In particular, there is a long history of free software and open-source software including a README file; in fact it is a requirement in the GNU Coding Standards.[6]

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[7] 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,[8] 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 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
CONTRIBUTING / HACKING Guide for prospective contributors to the project

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

Further reading

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

References

  1. ↑ Raymond, Eric S. (1996). The New Hacker's Dictionary. MIT Press. pp. 378–79. ISBN 9780262680929.
  2. ↑ Note that this is often no longer the case – but LC_ALL=C ls will show the older behavior.
  3. 1 2 Manes, Stephen (November 1996). "README? Sure--before I buy!". PC World. 14 (11): 366.
  4. ↑ "DECUS 10-LIB-4 Contains 10-210 through 10-241, except 10-223". pdp-10.trailing-edge.com. Retrieved 2018-03-03.
  5. ↑ "PDP-10 Archive: decus/20-0079/readme.txt from decus_20tap3_198111". pdp-10.trailing-edge.com. Retrieved 2018-03-03.
  6. ↑ "GNU Coding Standards: Releases". www.gnu.org. Retrieved 2018-03-03.
  7. ↑ "Code-sharing site Github turns five and hits 3.5 million users, 6 million repositories". TheNextWeb.com. 2013-04-11. Retrieved 2013-04-11.
  8. ↑ "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.

This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.