Why Is README Capitalized? (2015)

Why Is README Capitalized? (2015)

All-uppercase letters stand out and make the file easily visible which makes sense because it is probably the first thing a new user would want to look at. (Or, at least, should have looked at…) As others have already said, file names starting with a capital letter will be listed before lower-case names in ASCIIbetical sorting (LC_COLLATE=C) which helps make the file visible at a first glance.

The README file is part of a bunch of files a user of a free software package would normally expect to find. Others are INSTALL (instructions for building and installing the software), AUTHORS (list of contributors), COPYING (license text), HACKING (how to get started for contributing, maybe including a TODO list of starting points), NEWS (recent changes) or ChangeLog (mostly redundant with version control systems).

This is what the GNU Coding Standards have to say about the README file.

The distribution should contain a file named README with a general overview of the package:

the name of the package;
the version number of the package, or refer to where in the package the version can be found;
a general description of what the package does;
a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;
a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.

Since it is always good to strive for the least surprise of your users, you should follow this convention unless there are compelling reasons for a deviation. In the UNIX world, file name extensions were traditionally used sparingly so the canonical name of the file is README without any suffix. But most users probably would have no troubles understanding that a file named README.txt has the same meaning. If the file is written in Markdown, a file name like README.md might also be reasonable. Avoid using more complicated markup languages like HTML in the README file, however, because it should be convenient to read on a text-only terminal. You can point users to the manual of the software or its on-line documentation, that might be written in a more sophisticated format, for details from the README file.

>>> Read full article>>>
Copyright for syndicated content belongs to the linked Source : Hacker News – https://softwareengineering.stackexchange.com/questions/301691/readme-txt-vs-readme-txt

Exit mobile version