Editing README

{{Short description|Software information file}}
{{otheruses|Readme (disambiguation)}}
{{Use dmy dates|date=October 2019|cs1-dates=y}}
{{Use list-defined references|date=January 2022}}
[[File:README-cURL black trimmed.png|thumb|Screenshot of the README file of [[cURL]]]]

In software distribution and [[software development]], a '''README''' [[file (computing)|file]] contains information about the other files in a [[directory (file systems)|directory]] or [[archive (computing)|archive]] of computer [[software]]. A form of [[Software documentation|documentation]], it is usually a simple [[plain text]] file called <code>README</code>, <code>Read Me</code>, <code>READ.ME</code>, <code>README.txt</code>,<ref name="ESR_1996_Dict"/> or <code>README.md</code> (to indicate the use of [[Markdown]])

The file's name is generally written in uppercase. On [[Unix-like]] systems in particular, this causes it to stand out{{snd}}both because lowercase filenames are more common, and because the [[ls|<code>ls</code>]] command commonly sorts and displays files in [[ASCIIbetical|ASCII-code order]], in which uppercase filenames will appear first.<ref group="nb" name="NB1"/>

==Contents==
A README file typically encompasses:

* [[computer configuration|Configuration]] instructions
* [[Installation (computer programs)|Installation]] instructions
* Operating instructions
* A file [[manifest file|manifest]] (a list of files in the directory or archive)
* [[Copyright]] and [[software license|licensing]] information
* Contact information for the distributor or author
* A list of known [[software bug|bugs]]<ref name="Manes_1996"/>
* [[Troubleshooting]] instructions<ref name="Manes_1996"/>
* [[Credit (creative arts)|Credits]] and [[acknowledgment (creative arts)|acknowledgment]]s
* A [[changelog]] (usually aimed at fellow programmers)
* A news section (usually aimed at [[end users]])

== History ==
The convention of including a README file began in the mid-1970s.<ref name="Decus_1974_readme"/><ref name="Decus_1975_readme"/><ref name="PWB_1977"/><ref name="UNIX7_1979"/><ref name="BSD_1980"/><ref name="Langemeier_2011"/><ref name="Abdelhafith_2015"/> Early [[Macintosh System Software|Macintosh system software]] installed a Read Me on the Startup Disk, and README files commonly accompanied third-party software.

In particular, there is a long history of [[free software]] and [[open-source software]] including a README file; the [[GNU Coding Standards]] encourage including one to provide "a general overview of the package".<ref name="GNU_Standards" />

Since the advent of the [[World Wide Web|web]] as a [[de facto standard|''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. 

The popular [[source code]] hosting website [[GitHub]] strongly encourages the creation of a README file{{Spaced ndash}}if one exists in the main (top-level) directory of a repository, it is automatically presented on the repository's front page.<ref>{{Cite web |title=About READMEs |url=https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes |access-date=2024-05-31 |website=GitHub Docs |language=en}}</ref> In addition to plain text, various other formats and [[file extensions]] are also supported,<ref name="Github_2014_Markup"/> and HTML conversion takes extensions into account{{Spaced ndash}}in particular a <code>README.md</code> is treated as [[GitHub Flavored Markdown]].

==As a generic term==
The expression "readme file" is also sometimes used generically, for other files with a similar purpose.{{citation needed|date=February 2012}} 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:
:{| class="wikitable"
|-
|<code>README</code>
|General information
|-
|<code>AUTHORS</code>
|Credits
|-
|<code>THANKS</code>
|Acknowledgments
|-
|<code>[[Changelog|CHANGELOG]]</code>
|A detailed changelog, intended for programmers
|-
|<code>NEWS</code>
|A basic changelog, intended for users
|-
|<code>INSTALL</code>
|Installation instructions
|-
|<code>COPYING</code> <nowiki>/</nowiki> <code>LICENSE</code>
|Copyright and licensing information
|-
|<code>BUGS</code>
|Known bugs and instructions on reporting new ones
|-
|<code>CONTRIBUTING</code> <nowiki>/</nowiki> <code>HACKING</code>
|Guide for prospective contributors to the project
|-
|}

Also commonly distributed with software packages are an [[FAQ]] file and a <code>[[Comment (computer programming)#Tags|TODO]]</code> file, which lists planned improvements.

==See also==
* [[FILE_ID.DIZ]]
* [[DESCRIPT.ION]]
* [[.nfo]]
* [[man page]]

==Notes==
{{Reflist|group="nb"|refs=
<ref group="nb" name="NB1">This is often no longer the case{{snd}}but ''LC_ALL=C ls'' will show the older behavior.</ref>
}}

==References==
{{Reflist|refs=
<ref name="Decus_1974_readme">{{Cite web |title=PDP-10 Archive: decus/20-0079/readme.txt from decus_20tap3_198111 |date=1974-11-27 |website=pdp-10.trailing-edge.com |url=http://pdp-10.trailing-edge.com/decus_20tap3_198111/01/decus/20-0079/readme.txt.html |access-date=2018-03-03 |quote=[README.TXT is the DOC file for SPICE/SINC/SLIC] This failsafe tape contains the circuit analysis programs SPICE SINC and SLIC described in the Applications Software Bulletin Volume 4. requirements: SPICE requires FORTRAN-10 version 4 because of its use of Right adjusted Holerith data. Executes in about 47K. […] it also includes this file, the FOROTS to go with the SAVes and the source for SECOND.MAC, the timing routine. SPICE is broken into three parts: 1SPICE.FOR, 2 and 3. There is a printed document to describe each of the programs. These are included in the DECUS packet. The documentation and programs were originally developed by the E.E. department of the Univ. of Calif. at Berkeley on a CDC 6400. Except to convert the FORTRAN to the DECsystem-10 no changes have been made to the programs. For the test data SLIC and SINC have shown a slight variation with respect to the 6400, SPICE shows no variation. Good luck! Ashley Grayson 27-NOV-74 [end of README.TXT]}}</ref>
<ref name="Decus_1975_readme">{{Cite web |title=DECUS 10-LIB-4 Contains 10-210 through 10-241, except 10-223. |date=1975-03-27 |website=pdp-10.trailing-edge.com |url=http://pdp-10.trailing-edge.com/decuslib10-04/01/43,50322/read.me.html |access-date=2018-03-03 |quote=The files on this FAILSAFE tape constitute the UCI LISP system. They are for the most part documented in the UCI LISP Manual, available from the Department of Information and Computer Science at the University of California, Irvine, California.}} [http://pdp-10.trailing-edge.com/decuslib10-04/index.html]</ref>
<ref name="PWB_1977">{{cite web |title=Programmer's Workbench /sys/source/lex/README |date=July 1977 |url=http://minnie.tuhs.org/cgi-bin/utree.pl?file=PWB1/sys/source/lex/README |access-date=2020-01-25}}</ref>
<ref name="UNIX7_1979">{{cite web |title=Unix 7th edition /usr/doc/README |date=1979 |url=http://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/doc/README |access-date=2020-01-25}}</ref>
<ref name="BSD_1980">{{cite web |title=First 32bit BSD usr/doc/README |date=March 1980 |url=http://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/doc/README |access-date=2020-01-25}}</ref>
<ref name="ESR_1996_Dict">{{Cite book |title=The New Hacker's Dictionary |author-last=Raymond |author-first=Eric Steven |author-link=Eric Steven Raymond |date=1996 |publisher=[[MIT Press]] |isbn=978-0-26268092-9 |pages=378–79 |url=https://books.google.com/books?id=g80P_4v4QbIC |quote=Hacker's-eye introduction traditionally included in the top-level directory of a Unix source distribution, containing a pointer to more detailed documentation, credits, miscellaneous revision history, notes, etc. […] When asked, hackers invariably relate the README convention to the famous scene in Lewis Carroll's Alice's Adventures In Wonderland in which Alice confronts magic munchies labeled "Eat Me" and "Drink Me".}}</ref>
<ref name="Manes_1996">{{Cite journal |author-last=Manes |author-first=Stephen |author-link=Stephen Manes |date=November 1996 |title=README? Sure--before I buy! |journal=[[PC World]] |volume=14 |issue=11 |page=366}}</ref>
<ref name="GNU_Standards">{{Cite web |title=GNU Coding Standards: Releases |website=www.gnu.org |url=https://www.gnu.org/prep/standards/html_node/Releases.html#Releases |access-date=2018-03-03}}</ref>
<ref name="Github_2014_Markup">{{Cite web |title=Markup |date=2014-12-25 |website=GitHub |url=https://github.com/github/markup |access-date=2015-02-08}}</ref>
<ref name="Abdelhafith_2015">{{cite web |title=README.md: History and Components |author-first=Omar |author-last=Abdelhafith |date=2015-08-13 |url=https://medium.com/@NSomar/readme-md-history-and-components-a365aff07f10 |access-date=2020-01-25 |url-status=live |archive-url=https://archive.today/20200125153450/https://medium.com/@NSomar/readme-md-history-and-components-a365aff07f10 |archive-date=2020-01-25}}</ref>
<ref name="Langemeier_2011">{{cite web |title=Re: Origin of README |author-first=Jeff |author-last=Langemeier |date=2011-07-29 |via=Stackexchange |url=https://softwareengineering.stackexchange.com/questions/96966/origin-of-readme/97132#97132 |access-date=2020-01-25 |quote=[…] they had READMEs (actual physical printed files) for all of their punch cards and mag tape and pretty much anything else that was a "program". At that time you really needed one because of the labourous process that was involved with getting the created, ran, and everything else. These READMEs sometimes also included the actual printouts of how the punch cards were supposed to be punched as a form of error checking and debugging. The convention apparently also follows the old system in that with all the punch cards a "reem" of paper was attached with the statement README in caps printed on it, this had all of the instructions for use and loading of the punch cards into the system. For a time reference, this would have been in the 60s. […]}}</ref>
}}

==Further reading==
* {{Cite journal |title=Building a Better ReadMe |author-last=Johnson |author-first=Mark |date=1997-02-01 |journal=[[Technical Communication (journal)|Technical Communication]] |volume=44 |issue=1 |pages=28–36 |publisher=[[Society for Technical Communication]] |jstor=43089849}} [https://www.researchgate.net/publication/233611803_Building_a_Better_ReadMe][http://www.ingentaconnect.com/content/stc/tc/1997/00000044/00000001/art00004]
* {{Cite journal |title=Hypertext good choice for README files |author-last=Rescigno |author-first=Jeanne |journal=[[Technical Communication (journal)|Technical Communication]] |date=August 1997 |volume=44 |issue=3 |publisher=[[Society for Technical Communication]] |page=214 |jstor=43089876}}
* {{Cite magazine |author-last=Livingston |author-first=Brian <!-- |author-link=Brian Livingston --> |date=1998-09-14 |title=Check your Readme files to avoid common Windows problems |magazine=[[InfoWorld]] |publisher=[[InfoWorld Media Group, Inc.]] |volume=20 |issue=37 |page=34 |url=http://brianlivingston.com/windowmanager/archive/cgi-bin/new/livingst/980914bl.htm |access-date=2019-06-04 |url-status=live |archive-url=https://web.archive.org/web/20061118073226/http://brianlivingston.com/windowmanager/archive/cgi-bin/new/livingst/980914bl.htm |archive-date=2006-11-18}} [https://books.google.com/books?id=vFEEAAAAMBAJ&pg=PA34]
* {{Cite journal |title=Readme: Writing Notes - Meditations on the temporality of writing |author-last=Benjamin |author-first=Andrew |author-link=Andrew Benjamin |journal=[[Surfaces (Université de Montréal journal)|Surfaces]] |type=Electronic journal |volume=III |issue=12 |date=1996-09-15 |orig-year=1993 |pages=1–12 |language=en, fr |editor-first=Jean-Claude |editor-last=Guédon |editor-link=Jean-Claude Guédon |publisher=[[Les Presses de l'Université de Montréal]] |location=Department of Philosophy, [[University of Warwick]], UK |publication-place=[[Université de Montréal]], Montreal (Quebec), Canada |issn=1188-2492 |url=https://www.pum.umontreal.ca/revues/surfaces/vol3/benjami.html |access-date=4 June 2019 |url-status=live |archive-url=https://web.archive.org/web/20060220060754/https://www.pum.umontreal.ca/revues/surfaces/vol3/benjami.html |archive-date=2006-02-20}} [https://www.pum.umontreal.ca/revues/surfaces/sgml/vol3/benjami.sgml]

{{JargonFile}}

{{DEFAULTSORT:Readme}}

[[Category:Software documentation]]
[[Category:Filenames]]
[[Category:Community health files]]