Skip to content

Latest commit

 

History

History
51 lines (36 loc) · 2.48 KB

how-to-write-an-awesome-readme.md

File metadata and controls

51 lines (36 loc) · 2.48 KB
Raw
title date draft summary tags categories ShowCanonicalLink cover
Awesome README: A Template for Writing Useful READMEs
2020-07-13
false
A template for writing useful READMEs.
readme
documentation
tutorials
Tutorials
true
image alt caption relative
images/awesome-readme/cover.jpeg
A stack of folders on a table.
false

You can skip to the template here.

People can't use what they don't understand.

For open source projects, good documentation is as important as the project itself.

This is a guide to create useful READMEs that is best suited for small open source projects without dedicated websites having extensive documentation.

{{< figure src="/images/awesome-readme/meme.jpeg#center" title="Lame attempt at humour by 2020 Navendu" caption="Photo from imgflip" class="align-center" >}}

You can use this guide as a reference and build on top of it for your projects.

A Useful README

A README file is the first thing a user will see in your project. First impressions last, so it is important to make a good README.

A good README also helps:

  • your project cut through the noise and stand out
  • your users understand how to use the project
  • your contributors contribute to the project

There is not a one-size-fits-all when it comes to usability. But having the following sections can help:

  1. Title and description: Name of your project and an introduction to what it is about.
  2. Quickstart/Demo: A short introduction that users can follow to get started quickly with your project.
  3. Installation: A guide on how users can install your project.
  4. Usage: Details on how to use the project.
  5. Development: How users can build a development version of the project on their machines.
  6. Contribute: Guide for open source contributors looking to contribute to the project.

Considering all these, I have created a reusable template you can fork on GitHub.

Depending on your project, you might have very different README files. The idea is to use this as a reference as you write your README.

{{< figure src="/images/awesome-readme/meme-grasshopper.jpeg#center" title="Lame attempt at humour by 2020 Navendu" caption="Photo from imgflip" class="align-center" >}}