In every Git repository, the first file that one should read is the README file. Therefore is should provide concise and up-to-the point information on the contents of the repository. It could be considered as a manual for the repository.
In this post, I am providing a well-tried README template that I found useful in real-life projects over time.
Writing a README file requires some consideration and effort to make it useful for readers. But first of all, it should be considered who is the audience? It is important to consider the targeted audience factor as it determines their needs and their expectations - e.g.:
developer: code contribution, integration
end user: usage of the tool
project manager: technology stack, integration to other modules
What is the format of a Git README file?
Practically, markdown format (`md` extension) is the de facto standard of the Git README file. This markup language makes it possible to create documentation easier (e.g. Dillinger online markdown editor, or Bitbucket and GitHub have online editors to support it) and with its related HTML generation possibilities these documentations are easy to publish on the web.
What is the purpose of a Git README file?
The purpose of the file is to give information about the following topics:
Description (What the project is trying to solve?)
Features (What are the main functionality of the project?)
Prerequisites (What are the requirements of the project to operate?)
Installation (How can it be installed?)
Verification (How the installation could be tested?)
Usage (How can it be used?)
Related projects (What are the projects which has close relationship with this one?)
Documentation (Where additional information could be found?)
Licence (What kind of licence the project has?)
In the next section, the topics above are discussed.
The description should clearly state what the project does 1-3 sentences. Too long description is superfluous.
If the project is a fork of a standard library, include the following:
tag: git tag used for the fork
commit: short commit id where the fork happened
Upgade: description whether it is possible to upgrade to a newer version, or we are stuck for to the current version for any specific reason.
Prerequisites describe what software or knowledge elements are required to use the project. The typical prerequisite categories are: operating system, framework & technologies and knowledge.
Operation system is the most important factor as it is usually not switchable. (e.g. Linux, Mac or Windows. In some cases version numbers are also important.)
Framework & technologies infrastructure
Applied framework & technologies (usually with version numbers) are also important as if they are too heavy weight (e.g. requires to package 100 MB framework to include to the software package) or incompatible with the applied one are factors that prevent its usage. (e.g. GWT, Angular, Ionic, ...)
Required knowledge for the audience (mainly for the developers) to understand and contribute to the project. For example, contributing to logic inference engine, machine learning or text analysis frameworks requires considerable knowledge in those field.
It is crucial to provide step-by-step specification on the installation of a project. Installation instructions start after the user has the required environment (e.g. Prerequisites above), and ends right before calling the project either from the command line or from a web browser.
Providing a examples how to use our project is also necessary.
It is useful to list some projects that has strong relationship - either built on or used by - with this one. It often helps understand how to use or configure the current project.
It is recommended to provide detailed description of all the switches of the program, all the keys to unlock its potential. It is important to provide a simple README file while linking to a dedicated documentation website, with per-version documentation, as well as dedicated documentation on variants of the library.
The documentation could contain information about:
API documentation (e.g. Swagger API documentation)
Software engineering leader with 15+ years of experience with co-located and distributed multinational development teams. Successful projects include both research-intensive product developments and highly scalable and reliable distributed applications for customers (> 10M users). Professional interests include agile methodologies, specifically product strategy & planning, development workflows and metrics.