The README as First User Experience
An issue I find myself running into when I’m scanning through GitHub for places to contribute is that READMEs are occasionally treated as an afterthought, as if they have been tacked onto a repository as a perfunctory duty because that’s what you’re supposed to have. Sometimes they aren’t even present at all. This post is not calling anyone out or claiming that there is some widespread problem. GitHub is full of excellent, useful, and sometimes colorful READMEs. This post is for writers looking for a way into open source contribution by rewriting READMEs that need triage.
The README is the first impression, and impressions matter. It functions as both a book cover and a table of contents. It is often the first interface that a user will encounter, which makes it a UX concern.
Impressions Matter
Poorly constructed READMEs are like Mr. Mertle’s property in The Sandlot. They might resemble a dilapidated junkyard to the uninitiated, but inside the house are wonderful and meaningful items. Sometimes the external appearance can be an afterthought to the internal content.
The README is a way for repository contents to communicate with the user, not only in what materials are included, but in how easily those materials are accessed. Keep in mind that the entire purpose of the place is to be a “platform where you can store, share, and work together with others” (About GitHub). The README exists to facilitate working with others. The point is to help users better experience what you are attempting to share with them.
A quality README sets the tone. It lets users know what to expect from the repository and its maintainers. It says, “hey there, welcome. Here’s what we have and what you can do with it, and here’s how you can get started.” It communicates organization, confidence, and credibility. A quality README isn’t just easy to use practically. It’s easy on the mind.
What Users Are Actually Looking For
A quality README should answer all of a user’s explicit and implicit questions:
- What does this project do?
- How do I run it?
- What do I need first?
- What input is expected?
- What does it output?
- What is the airspeed velocity of an unladen swallow?
Understanding that not all users are the same or require answers to the same questions means that you, as a writer, need to frame the answers to those questions in such a way as to satisfy the greatest number of people. That means clarity, concision, and organization. Users should be able to scan efficiently and locate relevant information quickly.
Writing a README is a UX issue because it is the user at the center of everything. A repository owner isn’t writing and including a README for their own benefit, it is there for whomever needs to access the content and materials of their repository.
UX Principles Applied to READMEs
There are a few general principles to keep in mind when you are contributing to READMEs. If these components are missing, adding them will usually make a meaningful contribution.
Make sure that everything has a purpose and that that purpose is both clearly stated and that it appears up front. This goes for the overall organization of the README as well as each section and subsection. Remember that users for the most part aren’t reading through a README top-to-bottom, they are scanning over to find what is useful to them. Be clear and concise, and say exactly what something is and its purpose.
The best example of this is inclusion of clear headings. Use the fewest terms possible to express exactly what is contained within a heading. Likewise, make sure that the headings adhere to a clear heading hierarchy, both in terms of content and structure. Keep like items together, and list them according to logical flow. Before committing, see that your headings are correctly designated in markdown as well.
Being concise is more than just using fewer words. You also don’t need to include every little detail. If you find yourself questioning whether or not the history of brainstorming this project should be included, cut it. Do you really need to include class architecture breakdowns or file-by-file explanations? No, omit. Developer documentation is not default README material.
Be absolutely clear and direct about what something is. Leave no room whatsoever for ambiguity. If you can imagine a user scrolling up and down while reading through the material as if trying to make a decision, you’re not being clear and direct enough.
A UX-Focused README Structure
A good README structure is clear and organized. It also follows conventions. Conventions are very important in UX as familiarity is the precursor to efficiency. If your user has expectations of format and layout based on experience and the genre itself, well then by all means, give them those formats and layouts. Make it easy for them. That is not to say that there is strict adherence to exact formulation, but there are certain things that do need their place, such as a title at the top and the overview just below.
There are many online guides showcasing all manner of README organization, but here are the components in short form:
# Project Title
## Overview
## Features
## Requirements
## Installation
## Usage
## Output
## Contributing
## License
Headings should generally move from understanding to action. Overview explains the project, Features summarize capabilities, Requirements prepares the user, Installation gets them set up, Usage shows how to run it, and Output clarifies results. Contributing and License come last since they are secondary to using the project.
Small UX Improvements That Help
Even small changes can make a big difference. Adding an Overview header above an existing descriptive sentence alone improves UX. If the README you are revising is a wall of text, break them into smaller, manageable pieces by separating them with blank lines. Does the original text have lists of numbers or other unstructured data? Add a table (something you can do easily in markdown Tables). Does the original text mention something specific that a user would need to use the project at the top of the text, and then mention another thing the user would need several sentences later? Group those together and give them a header.
Why it Matters
README writing is UX writing. The whole point is to make things easier for the user. Remember as you contribute that structure and organization greatly improve READMEs because most users are scanning for what they need. Also keep in mind that even small changes can make a big difference, so if you find yourself thinking: “you know, a little tweak here could make this less confusing,” do it. You’ve contributed to the betterment of the project. You’ve made it easy.
Top comments (0)