Using Reddit & Twitter to Make Your README More Effective

Many lessons from my time at university have stuck with me throughout the years. One of the most important was in regards to technical writing (thank you to my CS 787 professor).

The lesson being that the process of technical writing is focused on being clear and concise. Every aspect of this technical work, whether it be visual or text, should be without redundancy or unrelated content.

This does not mean that your writing shouldn't be sophisticated or tedious, it just means you should be conveying relevant information. In other words, get to the point.

My Story

So that brings me to the README I've been working on. I have a repo that I wanted to be more alluring to potential users. This is a common situation that many open-source developers find themselves in. I didn't have too much experience writing high-quality READMEs.

Over years of using GitHub, I've seen some awesome READMEs with unique styles and crazy visuals/animations, but now I don't necessarily think that is always the most effective way to improve your README.

Last week I posted on various programming-related subreddits something along the lines of 'Looking for tips/criticism on my Github README?', about five in total. Furthermore, I DMed a couple of experienced open-source developers.

Over the following 48 hours, I received staggered feedback that I'm excited to share with you today. I've compiled the three most important points featured in the responses.

1. Informative Visuals

A picture is worth a thousand words. By that logic, too many pictures mean too many words. Take a look at this repo for example. There's a lot of images that clutter up the repo aesthetically. Are all of these images necessary? Too much large imagery damages the navigability of the page.

Imagery is very important as long it's purposeful. No-one likes reading a boring wall of text, but one or two branding/business images is enough. Your README should come off as a tool for potential developers to understand the purpose of your project, not as a sales pitch.

Furthermore, over-stimulating imagery can be a turn off to potential users as opposed to a mature, organized aesthetic.

This feedback led me to change the position and size of some of my more massive imagery. Stick to less than two branding images. Any other pictures/animations should be essential to either learning how to get up and running or understanding your project's purpose.

By the way, here's a link to my work-in-progress README for a React serverless platform. A star on the GitHub repo would be greatly appreciated if you liked this article. Thanks!

2. Navigability

For something like a GitHub page, organization and navigability go hand-in-hand. Users will likely reference your README multiple times. It's a one-stop shop for developers to find more information on specific topics (installation, dependencies, etc).

In my opinion, the most effective way to fulfill this navigability requirement is through the use of a Table of Contents. Many small to medium sized quality projects have some sort of ToC even if it's rudimentary.

This serves two purposes. First, it's a place for potential users to instantly navigate to their desired section. Second, it gives your README a structure to follow. Readers get a preview of what is to come as they continue forward. This structure results in a README that is organized and engaging.

Here's a tool that will automatically create a table of contents for an existing markdown document.

3. Expandable Content!

Now this one isn't as much feedback as much as it is my suggestion based on feedback. I didn't even consider using this markdown functionality until someone specifically suggested it to me. Turns out you can create expandable sections in your README with the following code:

<details>
<summary>Section Header!</summary>
<p>

Some information...

```python
# Here's some code
```

</p>
</details>

After trying this formatting method in my README, I can say that I'll probably be using it in the future. It made the layout much more concise and aesthetically pleasing.

As I said previously, no-one likes reading a wall of text. This dramatically improved the readability of my repo. What's great about this markdown feature is that it dramatically reduces README clutter without losing content.

Users don't have to leave the page if they want more detail on a specific subject, they just have to click the dropdown arrow. Here's my specific implementation for reference.

For a more robust discussion on drop-downs in markdown, take a look at this gist.

Conclusion

Thanks for reading! These three tips can certainly boost the effectiveness of your READMEs. Remember, the core goal of your README is to be clear and concise at every step.

The three suggestions above were chosen by me, based on feedback from multiple sources. Be sure to consider informative visuals, navigability, and collapsable content in your future projects.

Feel free to leave a response regarding any questions or concerns. I'll be sure to get back to you!

Update 12/22/2020:

I thought I should add a great resouce that I found called awesome-readme. You can view some of the best READMEs available on Github. There is plenty of material there to get inspiration from!