What Makes a Good README Doc?

You can tell how important a README file is just by looking at its name—it literally says, “read me”.

This document is often the first step in your users’ journey to becoming proficient in working with your product.

A high-quality README doc can make a difference between a user adopting or abandoning your product. What you include in it and how you present that information is very significant.

That’s why we’ve put together this article. Reading it will provide you with insights on what makes a good README document.

Sounds enticing? Let’s begin!

Completeness

A README file is usually the first that users read when they want to familiarize themselves with a new product or a project.

They assume they can get all the essential information they need from it before diving deeper into other parts of the documentation.

Therefore, you should ensure that you provide them with those essentials.

That means that your README document should be a well-rounded resource and that the users feel they know enough about the product after reading it.

Some README docs are very brief, and some are extensive, so the definitive list of what should be included in such a document depends on who you ask.

However, every README doc should start with a title.

The title is the first thing the user sees when they open your README, and it should give them an idea of what the project is about.

Can you tell what the project in the example above is about just by looking at the title? Most likely not.

However, the title does indicate that it’s about Git, and the company makes up for that lack of immediate clarity with additional information in the subtitle below the logo.

The subtitle tells you the story in two sentences—it’s GitHub for mobile devices.

Another essential part of a README doc is an introduction or an overview. It briefly summarizes the software and highlights its most notable features.

Below, you can see an example of an introduction from ThisMyPC’s README doc.

It’s brief, informative, and explains to users the project’s purpose.

It goes without saying that users also need information about installation, like the ones that Fiber provides to its users.

A title, an overview, and installation instructions are some of the essentials that make a complete README doc.

You can also add a “Getting started” or “Usage” section, a list of other helpful resources, a list of contributors, a license, and other information that you think the users would benefit from.

Brevity

Although it might seem like the brevity of a README file can be at odds with the striving for completeness we’ve discussed in the previous section, those two attributes can be present in one document.

Making sure that a document is concise doesn’t mean omitting essential information from it.

It only means that you straightforwardly provide that information and assess which information should be in a README doc and which can be in separate documents.

Don’t be tempted to put the contents of your complete documentation in a README file.

As we’ve already mentioned, a README should provide only the necessary information for users to get acquainted with your product and how to start using it.

For example, take a look at the table of contents of Peaks.js.

That looks like an extensive README document, right?

Well, what you can see above is only a part of what it contains. The Peaks.js README doc has almost 90 headings and subheadings in total.

To avoid making a massive README doc like that, you can separate content into multiple documents and include links to them in your README.

This is how Aimeos did it:

Those are all substantial resources, and putting the content from them in a README file would create one oversized document that’s hard to get through and find information in.

A README document should only be an entry point for users, one that provides them with basic information and points them in the direction of more detailed resources.

Scannability

A README document is a type of technical documentation, and you probably already know why people read technical documentation—to get the information from it.

That means that most users will open your README doc with the goal in mind to find a piece of information they need and move on with their work.

And it’s not that there’s something wrong with your documentation or that it is boring.

According to Jakob Nielsen’s research, users read only 28% of content on a webpage, and that’s if they devote all their time spent on a page to reading.

The more realistic percentage is even lower—about 20%.

So, whether they need an installation guide, usage information, code samples, or something else from your README file, users want to be able to find it quickly and efficiently.

A table of contents can be handy for helping your users in scanning the contents of your README file and finding the part they need.

You should include it right after the title and the introduction.

Also, as you can see in the example above, you can make your table of contents essentially a list of links to various parts of the document.

That way, a user can click on a bullet in the table and be instantly transported to the content they want to read.

If you find making a table of contents tedious, you don’t even need to make it yourself.

BitDownToc is a tool that generates a table of content and adds it to your Markdown files.

Therefore, there’s no excuse not to make your README document easily scannable.

A table of contents is like a map for your document; your users will appreciate you providing one.

Readability

Presenting your users with a README doc in the form of a wall of text that stretches out from the top to the bottom of the screen isn’t a good way to encourage them to read it.

On the contrary, you make it a chore for them to find the information they need if you ignore structuring your document and formatting it for increased readability.

How can you make your README file more readable? Luckily, it’s not complicated—you just need to implement a few elements.

Here’s how Raphael Campardou, an experienced cloud architect, sums them up:

As you can see, those are all formatting elements that you would expect in any type of technical documentation if you wanted to make it readable for your audience.

They make the text visually more appealing, space out the information, and make the crucial information easier to emphasize.

Let’s see what those elements look like in actual README documents.

The MeChat README heavily relies on lists to make information more digestible. It features multiple bulleted lists, like those below:

MeChat’s team also uses numbered lists, which can be very helpful in providing instructions that are easy to read and follow.

Headings and subheadings are also important factors in the readability of your document.

By using clear and informative headings and subheadings, you can inform your readers about what information to expect from the text, so they don’t have to read the entire document from start to finish.

In the example from PowerShell’s README doc above, you can see a heading that clearly states the nature of the following content, as well as two subheadings that help parse the information even more.

The paragraphs are also very brief, which, as we’ve mentioned earlier, is also beneficial for increasing readability.

All of the elements we’ve mentioned in this section are easy to implement with the help of Markdown.

That’s why you should use a documentation tool like Archbee, which supports Markdown syntax.

With a text editor like Archbee’s, you can use shortcuts while writing a README doc, and your text will be automatically formatted the way you want it to be.

That will make your writing and editing faster and easier, and your users will get the README doc they’ll enjoy reading.

Understandability

As you probably already know, README docs are mostly read by software developers, engineers, and other readers with high technical knowledge.

In other words, a layperson wanting to know more about a particular product will most likely look for a user manual, an onboarding guide, or some other technical document aimed at a wider audience.

However, just because a README doc is aimed at technically-savvy users doesn’t mean that you should assume that every reader will be familiar with the language and the topics it covers as well as you are.

And if you assume the level of your users’ knowledge, that can reflect in the language you use, which, as software designer Thomas Parisot explains, doesn’t lead to anything good.

A good README doc is easy to understand; the language is simple, and the text isn’t stuffed with technical jargon.

For instance, take a look at the language that this README doc by a user larymak uses.

It’s a conversational tone without an abundance of technical jargon, apart from mentioning full-stack web development, HTML, and CSS, which is unavoidable, given what the README is about.

Using simple language like that is important because, although most of your users have some amount of preexisting technical knowledge, you can’t know how much.

If we go further in the README doc from larymak, it’s easy to see how he explains concepts the user will encounter in his project.

He explains the actions (using the command line, installing software dependencies, etc.), what the user will learn (Git), and what the result will be (deploying the first website).

As we’ve mentioned, technical jargon is virtually impossible to avoid completely.

Still, if you provide explanations and context like in the example above, you can make your README doc understandable for users of any knowledge level.

Visual Appeal

As we’ve mentioned earlier, a good README doc is complete but also concise; it’s scannable, and easy to read and understand.

Creating a document that combines all of those characteristics is challenging, but adding visuals can make that task more manageable.

A README file with visual elements isn’t only more aesthetically pleasing than one without them.

Visuals also efficiently present information, showcase the product’s features and possibilities or do anything that you would otherwise need many sentences and paragraphs of carefully worded text to describe.

For example, do you want to show how the interface of your product looks? Use a screenshot like in the README doc for Node.js Chat.

Why write multiple paragraphs of text describing how each interface element looks when you can show it to your users with one image?

Similarly, you can put a logo at the top of your README doc to give a visually appealing first impression and grab the readers’ attention.

Pomolectron’s team did that while also continuing with two screenshots before providing the textual information about their tool.

The point of the visuals isn’t to make your README doc look pretty, although that’s a welcomed feature.

They can inform users about your project, show them its layout, how to use its features, etc.

In short, they make the document more understandable, and the instructions more precise, as well as visually appealing.

You can use visuals like GIFs, charts, already mentioned screenshots, or diagrams like the one below from the ReLaXed README doc.

Regardless of the visual type you choose, it will improve your README doc in essentially every way.

Up-To-Dateness

When it comes to usefulness, a README document is the same as any other type of technical documentation—to be useful, it needs to be regularly updated.

Users go to a README doc trusting that it’s a reliable source of truth and that its information is relevant for the newest software version.

Therefore, you should keep it up to date, so you don’t betray the trust that your users put in you and your documentation.

Take a look at how often this README doc below is sometimes updated.

That’s 11 updates in three days. Of course, how often you update your README doc depends on how often the crucial information about the software changes.

You can make planning README file updates easier if you have a roadmap for your product.

With a roadmap, whoever is responsible for updating documentation can see which changes to the product are made, which are in progress, and which are planned and when.

That way, writers can see which changes in the product should be reflected in the README doc and prepare for them.

What would happen if you neglected your README doc? It’s not hard to imagine—your users would soon realize that the information in it isn’t dependable, stop using it, and even abandon your product altogether.

Not updating your documentation sends a message that you don’t particularly care for the state of your resources and therefore don’t care for your users.

And that’s a reputation that you certainly don’t want.

Conclusion

A README document is a versatile piece of technical documentation.

For example, it can be very concise but with many links to additional resources. It can be packed with screenshots and GIFs but also only consist of plain text in short paragraphs.

The possibilities are endless, but one truth remains the same—it’s an essential document, and you should create it with a clear vision and care.

With the help of this article, you can undoubtedly do it. If your README doc has all the elements we’ve discussed, you can be sure it’s an excellent resource.

‍