Side Menu

Git README best practices

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. 
Note: The Git readme template could be found in the Git readme template repository.

Who is the audience?

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:

  1. Description (What the project is trying to solve?)
  2. Features (What are the main functionality of the project?)
  3. Prerequisites (What are the requirements of the project to operate?)
  4. Installation (How can it be installed?)
  5. Verification (How the installation could be tested?)
  6. Usage (How can it be used?)
  7. Related projects (What are the projects which has close relationship with this one?)
  8. Documentation (Where additional information could be found?)
  9. Licence (What kind of licence the project has?)

In the next section, the topics above are discussed.

Description

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:

  • Version:
    • 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.
  • Changes:
    • functional description and motivation of changes

Template
<project name> is a <utility / tool> 
that allows <target audience> 
to do <action>.


Example (DSA):

Features

It is usually important to state the scope of functionality - and usually those ones which are out of scope to avoid misunderstandings. A simple list with 1-2 sentences is usually enough.

Example (DSA):

Prerequisites

Prerequisites describe what software or knowledge elements are required to use the project. The typical prerequisite categories are: operating system, framework & technologies and knowledge.

Operating system

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, ...)

Knowledge

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.

Example (DSA):

Installation

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.

Example (DSA):

Verification

It is important to provide verification for the audience whether the installation was successful. 

Example (DSA):

Usage

Providing a examples how to use our project is also necessary. 

Related projects

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.

Documentation

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:

  • Developer guides
  • API documentation (e.g. Swagger API documentation)
  • Configuration guides
  • Changelog (e.g. CHANGES file. A widespread format is the GNU Coding standards changelog.) 
  • Migration guides (e.g. from version 1 to version 2)

Licence

README files are a convenient to state the license in use for a given project. Although, a dedicated LICENSE.txt file with the entire license content should be considered. 

There are a few websites where the most suitable one could be found: choosealicense.com


ByPosted
Share
Labels,