Readme: key details at a glance – including a template

The file name readme contains a simple in­struc­tion and for good reason. The readme file is typically the first file a developer will look at before beginning a project. It’s also important that de­velopers know how to write a good readme file that conveys all the relevant in­form­a­tion in a concise manner.

A readme file – often created as readme.txt or readme.md – usually contains important in­form­a­tion about the re­spect­ive system, project or software. To ensure users can find the file straight away, it should ideally be placed in the top directory level.

The file also fulfils different purposes for different users:

• For end users, a readme file answers questions about in­stalling, updating or using the software.
• For your own de­vel­op­ment work, a readme file provides two ad­vant­ages. On the one hand, a readme file written prior to the start of de­vel­op­ment provides a guideline for im­ple­ment­ing the project. On the other hand, it lets you resume work quickly if a project was pre­vi­ously set aside for a prolonged period of time.
• For other de­velopers, a readme file clarifies the codex and provides key in­form­a­tion for further de­vel­op­ment or use of a system, software or an open-source project.

Depending on the purpose of a readme file, the following content in par­tic­u­lar may be relevant:

• A general de­scrip­tion of the system or project
• The project status is important if the project is still in de­vel­op­ment. Use the file to mention planned changes and the de­vel­op­ment direction or indicate the com­ple­tion date of the project.
• The re­quire­ments on the de­vel­op­ment en­vir­on­ment for in­teg­ra­tion
• A guide to in­stall­a­tion and use
• A list of tech­no­logy used and any links to further in­form­a­tion related to this tech­no­logy
• Open-source projects that the de­velopers in­de­pend­ently modify or expand should be contained in a section on 'desired col­lab­or­a­tion' in the readme.md file. How should problems be handled? How should de­velopers advance the changes?
• Known bugs and any bug fixes
• FAQ section with all pre­vi­ously asked questions
• Copyright and licensing in­form­a­tion

It’s important to write the readme file so that it is always aimed at the end user. This will resolve most of the questions that po­ten­tially arise.

You can write and save a readme file in any text file format you wish. Formats may include readme.txt, readme.doc, and readme.1st. Depending on the platform the software should run on, the format of the readme file should be adjusted to the re­spect­ive system and the as­so­ci­ated text program. This ensures that the word processor is able to read the file.

Today, de­velopers mostly use the readme.md format. But what is an .md file? The file ending indicates a readme file in markdown format. Markdown converts text into HTML using simple format­ting char­ac­ters. A well-formatted and struc­tured readme file gives users a com­pre­hens­ive overview of the project.

We show you piece by piece how a readme.md is struc­tured and what format­ting options exist with the markdown format. To enable global col­lab­or­a­tion and prevent language barriers, you should always write the readme file in English.

Readme example in markdown format:

The top of a readme file should contain a suitable project name and a short ex­plan­a­tion about what the project is about. In markdown format, a hash sign '#' indicates the start of a headline. The number of hash signs de­term­ines the type of headline:

For extensive doc­u­ment­a­tion, a clear table of contents provides a useful overview:

The table of contents can be struc­tured with an ordered list in the readme.md. Simply insert the cor­res­pond­ing number at the start of the row and the list is created.

GitHub auto­mat­ic­ally adds IDs for the headlines in the readme file. The IDs are derived from the name of the headline and a hyphen '-' replaces the spaces. They are ideal for use as anchor nav­ig­a­tion in the table of contents. If the readme.md is intended for a different platform that does not auto­mat­ic­ally assign IDs to headlines, anchor nav­ig­a­tion can be created with HTML:

The table of contents are followed by the in­di­vidu­al blocks of content on the re­spect­ive points:

General in­form­a­tion about the project is important to provide an im­pres­sion of what it contains, in addition to a short ex­plan­a­tion. A markdown also allows you to insert graphics, screen­shots or other images into the doc­u­ment­a­tion. Simply write a de­script­ive word in square brackets followed by the URL for the image in round brackets (without spaces in between). Enter an ex­clam­a­tion mark in front, so that markdown in­ter­prets it as an image file.

You can create bullet points in an unordered list in markdown format using an asterisk '*' at the beginning of the line.

Links can be inserted anywhere in the readme.md. The structure is very similar to an image file, but without the ex­clam­a­tion mark at the beginning of the line. Write the word to be linked in square brackets, followed by the path to the website in round brackets (likewise without any spaces between).

Since a readme file is often used in the context of software de­vel­op­ment, it can be a good idea to include examples of source text in the document. Markdown provides a format­ting option for this, too. The code can be formatted with '```' at the beginning and end. You can also use code sections directly in the text.

A '>' at the start of the line will change the text into a quote.

Ordered and unordered lists can also be used in com­bin­a­tion in the readme.md. Simply continue the numbered list with the cor­res­pond­ing number.

We have in­teg­rated italic and bold words and passages for il­lus­trat­ive purposes. You can create italic text by placing the re­spect­ive word or passage between a simple asterisk “*” or un­der­score “_”. For bold format­ting, enter doubled asterisks or un­der­scores.

Tables can also be inserted into the readme.md using the markdown format. You can create tables using pipes '|' and hyphens '-'. The colons indicate whether the text should be left, right or centre-aligned.

Below you will find a summary of examples from the article as a readme template: