How to write a good README? #discuss

DEV Community

Top comments (19)

Working as a consultant in full stack web development. Also: Gamer & streamer / Cinema & music lover / Amateur cook / Beer & tea connoisseur

Location

France
Education

Degree in computer science
Work

Junior Consultant at Altran France
Joined

Jun 7, 2017

• Nov 26 '18

I usually structure my READMEs like this:

Quick description of what the project is and what it does
A quickstart "tutorial" on how to start using it
- Requirements
- Installation
- Configuration
- How to use it
An update/upgrade guide (unless it's quite complex, then I'll just put a link to a wiki page or something)
Where to find the docs
How to contribute to the project
How to report bugs in the project
The license

The structure and content might vary depending on the project but that's the default "template" I use when I write a README.

I like it that way because users just need to take 5 minutes to read it and know what's what.

jmfayard profile image

Jean-Michel 🕵🏻‍♂️ Fayard

One of the most salient features of our Tech Hiring culture is that there is so much bullshit. Everyone knows this. Each of us contributes his share. But we tend to take the situation for granted.

Email

jmfayard@gmail.com
Location

Berlin, Germany
Education

ENSIMAG + Universität Karlsruhe (TH)
Pronouns

he / him
Work

Kotlin, Backend, Open Source maintainer, Technical Writing
Joined

Apr 19, 2017

• Nov 26 '18

Very useful, merci!

michaeldimmitt profile image

MichaelDimmitt

Joined

Oct 19, 2018

• Nov 26 '18

Hope some of this info adds to the discussion.

Often a gif can be super-helpful to show how a project functions.
Example: github.com/MichaelDimmitt/gh_reveal

An image can likewise provide benefit.
Example: github.com/JohnCoates/Aerial

Logos or other images are also nice, they make the document more fun and less of a pain to read.
github.com/hashrocket/decent_exposure

Also, people often like the "shields" to show numbers like num downloads/week or tests passing.
shields.io/#/

Happy to add to the discussion further.
Mac app I like to use, Giphy Capture, for making gif's

cjbrooks12 profile image

Casey Brooks

What's the best way to get something production-ready? Use it in production.

Email

cjbrooks12@gmail.com
Location

Houston, TX
Education

B.S. Computer Engineering from Texas A&M University
Work

Mobile Architect at Credera
Joined

Apr 6, 2018

• Nov 26 '18

I like to think of a README very much like a college essay. Very formulaic, with a rigid and proven structure, with the intent of getting your idea across as quickly as possible.

While I am by no means an expert (or even really that great at following my own guidelines), here is the general structure I tend to stick with:

Introduction
- Project name and description
- Badges. Everyone loves badges. They help establish the trust between the project and the end-user. Badges are colorful and catch their eye, and ones like code coverage and build status build reputation. But don't go crazy. Much more than 1 full line of badges on a desktop gets too cluttery, but too few just looks lazy. 3-6 different badges is a good number for me.
- Close the introduction with a hook, something to get a passerby interested. It might be a screenshot, a video gif with basic functionality, or a very short code snippet. You want this to be the first thing someone notices when scanning your README, which should make them pause and be interested enough to actually read the description above it and spend their precious seconds scrolling to see what's below it.
Body
- Your README is not your documentation. Let me repeat this: Your README is not your documentation. It is an overview of your project, and it should get people interested in using it more.
- Definitely include a quick-start for the project. The shortest possible example that gets someone fully up-and-running. For a library, it might be how to add the dependency and a minimal integration into an existing project. For a framework, maybe a scaffold command followed by the most basic run command.
- A brief overview of features. Again, this is not documentation, it is just enough information to get users interested. For each notable feature, a small code snippet might be nice, and links to the full documentation page are a must. A project with a CLI might simply show a few of its commands, a library could do with a high-level overview of its API.
- Basic configuration. What is the entry-point into tweaking the quick-start example to suit their needs. Again, this is not full documentation, but simply the first place someone should look to start changing stuff. Link back to the full API docs from here.
- Next steps. After a user has completed the quick-start and has a basic idea of how to work with the API, it's time to lead them toward being a fully dedicated user. Link to the issue tracker, maintainer chat rooms, tags on Stack Overflow, and anything else they will need to keep going back to get get ongoing help or instruction.
Conclusion
- This is the last stuff you want end-users to see. If they made it this far, it's time to bring it all home. This should primarily be targeted at contributors and maintainers rather than end-users, but should be a good reassurance to the end-users of the quality of the project and its development progress. Here are some examples of good things to put in your README conclusion, in no particular order:
- Project license (although a link to the license is probably better, to keep the README shorter)
- Contributor guidelines (again, a link is better). Code of conduct, how to set up and build the project for development, that kind of stuff that prospective contributors need to know.
- References to other projects that inspired or are used in your project. Give credit where credit is due.
- For small projects, a list of all contributors might be nice, especially in rapidly-growing projects.
- Who's using this project?

My main point to all of the stuff above is that your README should be a springboard to everything that anyone needs to know about your project. It should primarily work to get new users intersted in trying it out, aid existing users in getting to the right channels for help, and hold the important bookmarks that maintainers will keep coming back to. And above all, Your README is not your documentation, but it should link out to the relevant pages in your full documetation whenever possible.

jmfayard profile image

Jean-Michel 🕵🏻‍♂️ Fayard

One of the most salient features of our Tech Hiring culture is that there is so much bullshit. Everyone knows this. Each of us contributes his share. But we tend to take the situation for granted.

Email

jmfayard@gmail.com
Location

Berlin, Germany
Education

ENSIMAG + Universität Karlsruhe (TH)
Pronouns

he / him
Work

Kotlin, Backend, Open Source maintainer, Technical Writing
Joined

Apr 19, 2017

• Nov 26 '18

That makes a lot of sense, and I would have probably fallen into the "Your README is not your documentation" trap if you hadn't point it out that clearly. Thanks a lot!

cjbrooks12 profile image

Casey Brooks

What's the best way to get something production-ready? Use it in production.

Email

cjbrooks12@gmail.com
Location

Houston, TX
Education

B.S. Computer Engineering from Texas A&M University
Work

Mobile Architect at Credera
Joined

Apr 6, 2018

• Nov 26 '18 • Edited on Nov 26 • Edited

You're welcome! It's definitely a temptation to use the README for documentation, since it is right there and Github displays it nicely for you. But dumping full docs into a README is just going to make it too huge for a new user to easily scan and they will leave disinterested, and it is too difficult to navigate for existing users to easily find what they need.

Github's Wiki is just as easy to use and gives you proper navigation for small, flat documentation needs. For larger and more complex docs, it's probably better to keep your markdown in the project and integrate it with a static site generator¹, so that the release of the project also publishes the docs to Github Pages or something like that. Either way, it's better for everyone than putting it in your README.

Orchid is a great choice of SSG for documentation. It can generate full Java or Kotlin API docs along with wikis and blogs and publish it all to Github Pages automatically, and it integrates seamlessly into your Gradle build
</shameless-self-promotion> ↩

sleepyfran profile image

Fran González

Music, code, repeat.

Location

Prague, Czech Republic
Work

Software Developer at Microsoft
Joined

Aug 9, 2018

• Nov 26 '18

I always thought of README as a quick look over a project: what is it about and how to set it up quickly with some examples and a link to the documentation in case I need it. In this area, after a quick look on yours, I think it does it perfectly.

sudiukil profile image

Quentin Sonrel

Working as a consultant in full stack web development. Also: Gamer & streamer / Cinema & music lover / Amateur cook / Beer & tea connoisseur

Location

France
Education

Degree in computer science
Work

Junior Consultant at Altran France
Joined

Jun 7, 2017

• Nov 26 '18

I actually put the full license in a dedicated file and the "license" section of the README only contains a link to it. That's probably a bit redundant but it's an old habit from the time when GitHub did not include the license in the project page header.
That's usually something I put in the full documentation to keep the README more lightweight and free of unnecessary technical details.

djangotricks profile image

Aidas Bendoraitis

Author of Web Development with Django Cookbook.

Location

Berlin, Germany
Education

Vilnius University, Lithuania
Work

Founder at "1st things 1st"
Joined

Jan 11, 2017

• Nov 26 '18 • Edited on Nov 26 • Edited

This article is pretty good about about the structure of README files: medium.com/@meakaakka/a-beginners-...

It also contains a template that you can reuse.

I especially like it when the contributors with avatars are listed at the bottom. It adds a great human touch.

vdedodev profile image

Vincent Dedo

Python tinkerer, regex lover, super introvert, ???, profit.

Location

Plymouth, UK
Education

CompSci Degree
Joined

Sep 1, 2018

• Nov 27 '18

Conciseness is key. My experience of READMEs has been when I need to learn something and being able to pull out the essentials. I think the README you linked is way too wordy and would suggest trimming it down.

siddharthshyniben profile image

Siddharth

Making wild out-on-a-limb schemes which can change the world if they work, but probably wont.

Email

siddharth.muscat@gmail.com
Location

Kannur, Kerala, India
Joined

Apr 1, 2021

• Jul 12 '21

I'm currently writing a post on this, I'll send you a link when it's done.

However, according to me the core idea is the README should be a gateway to other pieces of info. Keep minimal info in the README, like how to install, a quickstart code sample, and links to the contributing, docs, license etc. Only exceptions when your project is really tiny

jmfayard profile image

Jean-Michel 🕵🏻‍♂️ Fayard

One of the most salient features of our Tech Hiring culture is that there is so much bullshit. Everyone knows this. Each of us contributes his share. But we tend to take the situation for granted.

Email

jmfayard@gmail.com
Location

Berlin, Germany
Education

ENSIMAG + Universität Karlsruhe (TH)
Pronouns

he / him
Work

Kotlin, Backend, Open Source maintainer, Technical Writing
Joined

Apr 19, 2017

• Jul 12 '21

Looking forward to reading it :)

revskill10 profile image

Truong Hoang Dung

I hate technical debts, very much. Learning to clean debt out of my life.

Joined

Aug 2, 2018

• Nov 27 '18

Writing README along side with source code/feature development.
If you separate README development from source code development, you're doing it wrong.

Treat README like source code, it's an art.

So the answer is: it actually depends on the project itself.

tpom6oh profile image

Alex Verein

Used to be a mobile developer, now I build dev tools, working with 10+ programming languages. Follow me on Twitter for more dev content

Location

Moscow, Russia
Work

SWE & Developer Advocate at Avo
Joined

Aug 6, 2020

• Mar 18 '21

Take your product, imagine that you don't know it and onboard yourself. Even better to onboard a friend and note everything that's happening

View full discussion (19 comments)