Improving / updating our READMEs

Archive Outreach
1

I spent some time recently reading through all our READMEs and also reviewing how a bunch of other organisations structure theirs.

With aims of helping people understand:

  1. who we are,
  2. what we’re doing,
  3. how they can get involved,

I drafted a proposed new README here: GitHub - jonathanbarker/templates-

This would fit nicely with the work @jonathan is leading on the website refresh - focusing on clear and easy channels to contribute to Status.

Since I’m not an expert in this area - would welcome feedback from others if you have suggestions. cc @cryptowanderer @Hutch @PascalPrecht @oskarth since we’ve chatted about related topics recently.

2 Likes
2

Hi @j12b!

This is super nice, thanks for putting this template together. So in general I think it’s also important to keep in mind what the Readme file is originally for (not saying it can’t be used in different ways).

Usually a readme is a file that, well, authors of a software want users to read. Most of the time this includes information about how to install the thing, or even a few gotchas to keep in mind that people could run into.

However, with GitHub and the ability to read readmes right in the browser, this has changed a little and people tend to use it more and more as a “presentation” kind of file, to let people know what the project is about, how to install and use it and where to find help.

So with that in mind, I believe your templates are pretty much spot on.

There’s one case, however where I think it’d be beneficial to keep the readme short and concise. That is, when the project has a complete documentation on various topics a reader might be interested in (what, why and how / installation / usage etc). If there’s good documentation in place, it’s probably better to drive people towards that and have them actually spend less time with the readme.

As a matter of fact, I believe a lot of people don’t really want to read through every bit of a readme to find the detail their looking for. Often, they just skim through it to find code snippets on how to install and use the software.

A very good example of that is Angular’s readme: https://github.com/angular/angular/blob/master/README.md

Notice how it simply gives you a punchline about what this project is a about, a link to the quick start, links to where to find help and the changelog.

^ This makes a lot of sense, because usually that’s information you want to find quickly. However, the bread and butter of all of these things is actually covered in the docs.

I was planning to do the same thing with Embark’s repository (/cc @iurimatias)

**So I guess, bottomline: **

If you don’t have good documentation in place, putting the essentials in the readme is a good idea. However, if you do, it’s probably better to keep it as short as possible and refer to the official docs.

Hope this makes sense.

3

Let me just add to that, that your readme template is by far not as complex as it could be, so it’s probably perfectly fine to use that amount of content in combination with good documentation.