README
Software information file
A README file contains descriptive information about the content of a directory in which the file is located. The scope of the information generally includes the files of the directory, and may include descendant directories, or even the full directory tree. The name is intended to draw a user's attention to important and orientational information about the directory content. A rule of thumb for one unfamiliar with the content of a directory is to read the README file before other files. Although the name README is often used, there are many other similar names used for the same purpose including "Read Me" and "READ.ME". Sometimes the file name includes an extension to indicate the file format such as "README.txt" for plain text or "README.md" for Markdown. The file's name is often all caps.
A README file in an archive acts the same as in a directory since an archive is functionally a directory stored as a single file.
01Content
Lacking standardization, the format and content of a README file varies dramatically. For a software project, a README file commonly includes information such as:
- Configuration instructions
- Installation instructions
- Operating instructions
- A file manifest (a list of files in the directory or archive)
- Copyright and licensing information
- Contact information for the distributor or author
- A list of known bugs
- Troubleshooting instructions
- Credits and acknowledgments
- A changelog (usually aimed at fellow programmers)
- A news section (usually aimed at end users)
02History
The convention of including a README file began in the mid-1970s. In Unix, where most file names were in lowercase, the name was capitalized so it would stand out and appear near the beginning of ASCII-ordered lists. Early 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".
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.
The popular source code hosting website GitHub strongly encourages the creation of a README file , if one exists in the main (top-level) directory of a repository, it is automatically presented on the repository's front page. In addition to plain text, various other formats and file extensions are also supported, and HTML conversion takes extensions into account , in particular a README.md is treated as GitHub Flavored Markdown.
Sources and credits
This article is adapted from the Wikipedia article “README”, written by its contributors and licensed under CC BY-SA 4.0. Fathomly has changed the layout, removed citation markers, navigation and maintenance notices, and adjusted punctuation. This adapted version is shared under the same license. For references, see the original article.
Images, from Wikimedia Commons:
- README-cURL black trimmed.png by WhoAteMyButter, CC0
Fathomly is not affiliated with or endorsed by the Wikimedia Foundation. Spotted a problem? Tell us.
