DEV Community

Cover image for How to write a kickass README

How to write a kickass README

James.Scott on October 28, 2019

Arguably the single most important piece of documentation for any open source project is the README. A good README not only informs people what the...
Collapse
tautvydasderzinskas profile image
Tautvydas Derzinskas

Emojis is a matter of taste.

You are missing two important things:

  1. Table of contents. (allows you to see summary of your readme file without scrolling + quick navigation)
  2. Logo - makes your readme and whole project more professional
Collapse
scottydocs profile image
James.Scott Author

Agreed re:emojis and logo! Have made an edit. Thanks!

The risk of adding a TOC is you push all the important information like the intro/project summary etc further down. I’d only really use one if your README is incredibly long (or I’d move some of that content into another file).

Collapse
willvincent profile image
Will Vincent

I think if you've got enough info to warrant a TOC, that should follow the initial intro section of the document that describes what the thing is, etc.. AND, that's probably a good time to also think about splitting it into multiple files, ie: instead of a contributors section, a separate contributors.md file, etc.

Thread Thread
benracicot profile image
Ben Racicot

+1 this is what I did. Once it gets to a certain length ah... you kind of need one up top.

Collapse
christopherkade profile image
Christopher Kade

There's also this great tool to generate a README based on your package.json 😄 I use it for all of my projects

Collapse
moopet profile image
Ben Sinclair • Edited on

That's very specific for Github projects that fit in a fairly narrow window. I know the point of a template is that you use it as a starting point, but for most of the stuff I do, I'd be deleting more than half the template every time.

Collapse
scottydocs profile image
James.Scott Author

That's the one linked at the bottom (in the resources) 😉

Collapse
christopherkade profile image
Christopher Kade

Aaah sorry I missed it ! Glad you did, it's super useful. Great article James 😄

Collapse
douglasfugazi profile image
Douglas Fugazi

Thanks for your recommendation, it seems easy and helpful to work 💪

Collapse
togakangaroo profile image
George Mauer • Edited on

Take a cue from those same old school manuals you reference as to what they include. Who cares about badges and emojis. That's marketing. Put marketing on your site. This is about getting shit done

Most non obvious projects should have a glossary of terms. These are business or non-standard technical terms you need to understand to make sense of the code.

You should also probably have an architectural overview. Charts (plantuml + graphviz ftw there). Enough to convey a high level understanding of how the darn thing is built. There is nowhere better for this.

Justifications for potentially controversial architectural decisions can probably go into issue and or discussions but at least link em!

I've also found a short FAQ section to be a good idea here.

Justifications of potentially controversial decisions as well, as there is simply no better place for them and its important for people to understand.

Collapse
scottydocs profile image
James.Scott Author • Edited on

Thanks for the feedback!

I honestly wouldn't advise including a glossary in a README. Make it a separate file or have it on your documentation site. You can add links to definitions if you really need to.

A simple high-level architecture diagram isn't a bad idea if you want to mess around with Graphviz but anything more complex I'd keep to a separate doc.

If you need an FAQ you should be asking, why aren't these questions answered in my README?

Collapse
togakangaroo profile image
George Mauer • Edited on

But listen to what you yourself are saying James. You - very correctly in my opinion - start of with the historical perspective, but now are recommending discarding the lessons that were learned in how to compose those very documents. That might make sense, sure, but you'd agree I hope that it would at least need to be justified.

What is the purpose of a README? It should be everything you need to get started in working with the project, right?

And more specifically, the huge benefit over separate docs is that it lives alongside your code and can change in tandem. So if an important architectural concern changes but the related docs do not, you can see and comment on it right in the same pull request! So maybe, once your project stabilizes you can move that stuff to a different linked document but frankly most projects will never get to that level of stable.

As for FAQ... Well if you put it into the README then it *would*be answered there 😉, but I take your point. The reason I end up having it anyways is as a concession to both suboptimal organization (shit, this is important but there's no obvious section for it), and to people who are in a hurry to get stuff done and don't read all the docs.

Thread Thread
scottydocs profile image
James.Scott Author • Edited on

I'm not saying to discard anything. The early READMEs were absolutely terrible. If there was a lesson to be learned it would be: Do not copy the format of the example README from 1974 😂

I get your point re: it's good to have stuff in one place but if you're using a docs-as-code approach then your docs live alongside the code anyway so all of your docs files will be updated as you update the code.

I guess it's personal preference re: FAQs but for me, they don't belong in a README. Relevant article here: FAQs Are A Code Smell.

Thread Thread
togakangaroo profile image
George Mauer

I mean the people that created the stuff a lot of our works is based on surely had some aspects of it figured out :)

And yeah I agree an FAQ is absolutely a smell, it's just also often a reasonable concession for when you don't have resources for a more elegant solution.

Collapse
tterb profile image
Brett Stevenson

This is a great (and necessary) introduction to writing helpful READMEs.
The only thing I would add is that I've found GIFs to be even more helpful than screenshots for showing off the functionality of your project.

Collapse
scottydocs profile image
James.Scott Author

I have used GIFs in the past (and yes, can be a great way to highlight functionality). You just need to mindful that you’ll need to update them if anything visual changes in your project (like with screenshots).

Collapse
iamshadmirza profile image
Shad Mirza

I use this module github.com/kefranabg/readme-md-gen.... It's easy, straight forward and generates beautiful readme within seconds.

Collapse
scottydocs profile image
James.Scott Author

Hey Shad, thanks! Yeah, that’s the last link I put in the resources (see bottom of the page) :)

Collapse
iamshadmirza profile image
Shad Mirza

My bad, missed it. Good article bdw.

Collapse
hpbl profile image
Hilton Pintor

I've made an open source project to generate README section recommendations based on the most popular repositories for each language on GitHub. Would love yo get your thoughts and contributions: hpbl.github.io/WRITEME

Collapse
scottydocs profile image
James.Scott Author

Sure. Is there a repo link so I can submit a pull request or is it private?

Collapse
hpbl profile image
Hilton Pintor

Sorry for the delayed response, but yes: github.com/hpbl/writeme

Collapse
blackmamba profile image
The Black Mamba🔥

Contributors list will be great too,i have created an opensource app which can be used to create markdown ,it allows to reuse commonly used items such as licence or contributors list.
markdownapp.now.sh/

Collapse
guneyozsan profile image
Guney Ozsan • Edited on

I feel like screenshots are a little bit overlooked in repositories. I especially find gif crops that display core features very useful. They are focused and attractive while it takes only a few seconds to grasp context. When applicable screenshots and gifs can provide a nice motivation to drive people into the project.
Sample gif

Collapse
jrop profile image
Jonathan Apodaca

Dude, your profile pic is awesome.

Collapse
scottydocs profile image
James.Scott Author

Haha thanks!

Collapse
guneyozsan profile image
Guney Ozsan

Nice read thanks!
At minimum I try to include these sections:

  • Title
  • Log line
  • How to install for development
  • How to install for usage/production
  • How to contribute
  • Style guide source
  • License
  • Contact and other links
Collapse
dietergeerts profile image
Dieter Geerts

Or you could just follow the standard-readme specs: github.com/RichardLitt/standard-re...

Collapse
scottydocs profile image
James.Scott Author

Cool, I didn’t even know this was a thing!

Collapse
douglasfugazi profile image
Douglas Fugazi

Very accurate all the info. Maybe I should re-edit all my Readme based in this info. Thanks 👍

Collapse
benracicot profile image
Ben Racicot

Any extended advice on what legal to put in a readme? Especially wondering about the situations where you do not want anyone to be using the code. "closed source" if you will.

Collapse
scottydocs profile image
James.Scott Author

This is a great question (you also reminded me to add choosealicense.com to the licenses section!) but I don't have an answer for you I'm afraid and I don't want to give you bad advice.

However you may find some useful info in this chapter on Non-Open Source Licenses and The Legal Side of Open Source. Hope that helps!

Collapse
benracicot profile image
Ben Racicot

Wow, great resource nonetheless. You've pointed me towards a "Classic Proprietary License" for projects that contain open source code but is not licensable. Thanks for the great article and reply!

Collapse
codeposse profile image
T.Hunold

You lost me at Ruby.

Collapse
tallship profile image
Bradley D. Thornton

You had me at Hello.

Collapse
codeposse profile image
T.Hunold

Missed opportunity... You had me at 'echo: hello world'

Collapse
devint profile image
Quétier Laurent

I'm happy to see good tips to add with my already good practices 😜
Thank's for this post.

Collapse
danedens profile image
Dan Edens

Emojis are garbage.

Collapse
arturssmirnovs profile image
Arturs Smirnovs

What a nice article, check my tool here, i made this github readme generation tool. #justforfun

Collapse
aayushidroid profile image
Aayushi Sharma

I created My Github readme

Hi there 👋

I am aayushi Sharma. I Love ❤️ programming and currently working as Machine learning engineer.

Skills

  • Python
  • JavaScipt
  • React
  • Web Development
  • Machine Learning
  • Deep learning
  • Natural language processing
  • App Development

Things got bugs, gonna smash them one by one

codeperfectplus






Collapse
mmesson profile image
Manuel Messon-Roque

Good stuff

Collapse
vuelancer profile image
Vuelancer
  • I have created a youtube tutorial for markdown file for begineers!
  • Additionally, I have added a demo for github new profile-level README feature
  • youtube.com/watch?v=x0Boemw9teU
Collapse
mnepita profile image
Martin Nepita

Thank you sir!

Collapse
hasii2011 profile image
Humberto A Sanchez II

hmm

Collapse
functor profile image
Santana16

Great article! Thank you. Question: would you insert the link to project's documentation and if so, where would it go?

Collapse
franksierra profile image
Frank Sierra

Nice!! Screenshots for me, are one of the most important things.