If you work in software development, you’ve probably read many different README docs.
Some were clear and effective, and some much less so.
Since the README file often serves as the entry point for users to dive into your project documentation, it stands to reason that a well-written document can make a big difference in how users will perceive your project in general.
In other words, whether you’re developing an open-source library or repository that relies on dev community contributions or a commercial software solution that needs to appeal to end-users, you need a great README doc.
So, here are five tips on how to create one.
Take Your Audience Into Consideration
Before creating a README doc, you should define your intended audience in terms of their technical expertise, educational background, and work experience.
Simply put, who will be reading your README?
As we indicated in the intro, this will depend on the project for which you’re creating the README document.
For example, a consumer-facing mobile or web application may have a README file for non-technical users who want to learn more about the app, its features, and its installation requirements.
On the other hand, an open-source software library, command-line tool or utility, or GitHub repository will have a README file intended for a more technical audience like code contributors, external developers, and other tech-savvy users.
GitHub’s section about READMEs states:
You can add a README file to your repository to tell other people why your project is useful, what they can do with your project, and how they can use it.
In this example, your README file is intended for technical users, so that fact will shape its content and style.
In such cases, your doc should include technical details, usage examples, and explanations of the code structure and implementation because technical users expect—and rely on using—this information to better understand your project.
For instance, this means you don’t want to oversimplify the concepts and terms you’re using.
However, it’s still highly recommended to explain the technical terms and acronyms when they appear in the text to avoid any misunderstanding stemming from the readers’ individual interpretations.
This will ensure the accuracy and consistency in using the technical terminology throughout the README and other documentation, regardless of your intended audience’s expertise level.
The same applies to other principles behind creating a great README we mentioned (clear and concise language, detailed explanations, and examples), as well as those covered in our tips below.
Overall, by knowing your audience and considering their level of understanding, educational background, and work experience, you can strike the right balance and create a README that meets the needs and expectations of your readers.
Include All the Essential Sections
A great README doc should include all the essential sections that readers expect to find.
Otherwise, the README doc will be of little use to readers who are trying to find out what the project is all about.
Of course, these sections will vary depending on the type of project you’re presenting, your audience's assessed level of technical knowledge, and their specific needs.
However, there are some basic sections that almost any README will have, such as the project title and description, installation and usage instructions, license and contributing information, including credits.
So, let’s start with the project title and description.
As you can see, the title should be short but informative, and the description should briefly explain what the project is and what it does.
This is also the first thing users will see when they visit your project page, so it’s important to make it clear and concise.
Next up are the installation instructions, i.e., how developers can get your project up and running.
In other words, this section should include information on any dependencies, configuration, and other requirements, as well as step-by-step instructions on how to install the product.
This section should also include any troubleshooting tips or provide a link to a separate section that deals with common installation issues users might encounter—a troubleshooting guide.
The usage section—where you provide instructions on how your project can be used—often includes examples and demos of different features and functionalities.
These are often presented in the form of visual aids, such as code snippets, GIFs, and other images, which we’ll discuss later.
For instance, the README below provides several examples of how different Axios library functions can be used and how requests should be made, backing each example with a relevant code snippet.
Of course, simpler projects may not require such examples and demos when their purpose and usage can be easily explained through text, while users of more complex projects might expect them.
Moving on, your README should (if open source) include the contributing section where users are provided information on how they can contribute to your project.
This is usually followed by credits, where you acknowledge any previous and current contributors to your project, as well as any third-party libraries or resources that were used.
Finally, the license section provides information on the legal terms under which contributors and other developers can use your project.
In summary, despite many possible variations, your README doc should follow a certain basic structure and include all the essential sections to help users quickly understand and navigate your project.
Format Your README Doc for Readability
When creating a README doc, it's important to consider how the reader will navigate and understand the information they encounter.
In other words, a README should be formatted in a way where the reader can quickly scan its contents to find the information they need, which is best done by providing a table of contents listing the essential README sections we just mentioned.
Beyond that, formatting a README doc for readability includes using:
- headings and subheadings
- bold and italic for emphasis
- short paragraphs
- bulleted and numbered lists
The overall goal of README formatting is to make the text easier to read—less cluttered or confusing—which increases the likelihood that the reader will correctly understand what is written.
To make the README doc more readable, most developers will use a formatting language, and Markdown is definitely one of the most popular options.
According to Markdown Guide:
Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents.
In essence, you add Markdown syntax to the text indicating how that text should look when rendered as HTML or some other format.
Here’s an example:
Formatting your README for readability in this way is easy to do with Archbee, our complete documentation platform with a simple and intuitive editor that supports Markdown formatting.
The platform makes it easy to write, structure, and format README docs using Markdown.
Moreover, since your README is only one part of your project documentation, you might also need a platform that helps you create, organize, and share all your other project documentation referenced in the README.
Archbee has you covered there, too.
Simply put, this feature-rich platform allows you to create and host (on a documentation website with your own domain) all project documents like developer guides, API documentation, knowledge base,wikis, and READMEs.
If you want readers to be able to easily navigate the contents of your README doc and understand the information they need to work with your project, it’s a good idea to use a platform that will allow you to write, structure, and format the doc for readability and accessibility.
Add Images for Visual Appeal
The nature of READMEs is clear from their name, but that doesn’t mean they need to look like a dense wall of dry technical text—and there is a real risk of that, especially when README docs are not well-formatted. This affects the reader’s experience and engagement with the text.
That’s why adding images to a README doc will make it more visually appealing to the reader.
Well-placed images—at least the logo or a relevant chart or other illustration—can break up the text and make the doc more visually appealing, like in this example.
On top of that, images can be used to showcase the key features of your project in an easily understandable way, and show what your project does.
Again, this has to do with how humans perceive images versus text.
For example, a complex interface or process may be difficult to explain with words alone, but diagrams, flowcharts, and screenshots can provide a clear visual representation that’s much easier to understand.
As for how images can be added to a README doc, you can again use Markdown, but make sure the image size and format are suitable to avoid frustrating users with slow load times.
For instance, here’s how to do that in GitHub using Markdown syntax:
Overall, adding images to your README can improve its visual appeal and help to better communicate the key features of your project to readers.
That way, you can improve their user experience and their understanding of the written text.
Split Your README Into Additional Docs
Of course, it may be tempting to put all of the information you feel your users need to know in one README file, but the result will probably not be a document that is short and to the point.
Instead, you will have a README file that’s too long, difficult to navigate (even with a table of contents included), and tiresome to read.
As we indicated a few times in this article, this issue can be prevented by splitting the README into additional docs, allowing you to cover only basic information in the main one, and link to other docs that explain that information in more detail.
For example, considering the size of the IBM-built open-source design system shown below, its README would be much longer and less comprehensible if it aimed to include all the relevant info on one page.
Instead, the opening README is short and well-organized, with multiple links directing the reader to other pertinent information.
This way, a shorter README acts more like an entry point from which you can explore more detailed docs covering these topics, which is very practical for more complex projects.
In such cases, the README serves a function similar to the landing page on your dedicated documentation website, should you decide your team and/or users need one.
Summing up, splitting your README into several docs and thus providing only the most important info in the main document, along with links to relevant additional resources, will ensure that readers have a clear overview and understanding of the project, as well as easy access to more detailed information.
Conclusion
To create a great README doc, you need to be aware of the intended audience, and make sure it doesn’t omit any essential sections so that the readers can find all the information they might need and expect from such a document.
To ensure its readability, you need to format it properly and add images for visual appeal.
Finally, if it becomes too big, split the README into several docs that give the interested party more insights about specific areas without overburdening the main document.
By applying these tips, you can effectively communicate what your project is, what it does, and how to use it, enabling users to quickly understand and easily find their way through your project.
The end result?
A great README showcasing your project and professionalism, satisfied and engaged users, and much less time spent on repetitive explanations and support requests.
