A new look for PatternFly’s React README files

Abigael Donahue
Mar 11, 2020 · 5 min read
Hands covered in paint, holding a pencil and a paintbrush
Photo by Alice Dietrich on Unsplash

When you think of content, chances are GitHub isn’t the first thing that comes to mind. GitHub is primarily for developers, right?

Right. But developers need content, and GitHub can be great for that too.

Specifically, README files come in handy when exploring new projects and setting things up, as well as contributing code and sharing your work with the world.

PatternFly has various GitHub repos filled with README files. We recently decided to take on a rather ambitious initiative: to make those README files amazing.

In other words, we’re working on revamping PatternFly’s README documentation so that the content is formatted and delivered in a way that works for users. We know we can’t go from 1 to 100 in a matter of days, so we’re breaking this into smaller parts.

The first part? PatternFly’s React repo.

We’ve sifted through lots of content, conducted plenty of brainstorm sessions, drafted various file structures, and more. Now we’re ready to share our story and tell you how PatternFly’s React repo just got better. Let’s get started!

Why spend time on something like this?

I wasn’t alone, either. Various developers were also interested in making these files the best they could be. After chatting with some users and contributors, I learned that the React repo’s content experience could be better. For example, navigating the content and finding needed information wasn’t always easy or intuitive. On top of that, each article had a different look, feel, and format. This inconsistency added to the confusion for users.

So with that in mind, we agreed that our challenge wasn’t creating information — we have plenty of it! Instead, we needed to format and deliver the information in a way that makes sense for users.

The research process

Collaboration

I partnered with designers and developers to learn more about the README files: Who uses them? Who contributes to them? Most importantly, what are we trying to achieve with them?

A small group of us met regularly to discuss the documentation so that we all had a good understanding of its purpose and audience before diving into the revamping efforts.

Discovery

Long story short: The React repo gets the most attention from users.

As mentioned earlier, PatternFly has quite a few repos with README files. We couldn’t do everything at once, so we needed to pick one repo to start off with. After reviewing some metrics, we learned that the React repo has the highest usage. On top of that, the majority of the usage is reading, not contributing. So naturally, we went with that one — what matters most to users matters most to us.

Then we conducted a light content audit to discover what files and information existed in the React repo. This involved reading through each file, adding it to a database, and documenting each file’s structure. As a result, we could take a close look at the content as a whole and easily identify duplicates, outdated content, and structural patterns.

Learning

We learned a couple things in this phase:

  • How others do it: We took a look at various open source packages with the highest number of dependent projects, like lodash/lodash, expressjs/express, and visionmedia/debug, to name a few. We closely examined these repos’ README files, especially their structure, information, and more. These repos served as inspiration as we thought of new approaches for PatternFly’s content.
  • Best practices: After looking through how some of the top projects do it, we then researched advice and guidelines from various sources about creating README files. We read through templates, techniques, and other ideas from README file creators. Again, we were inspired. There are so many great ideas out there.

After collecting tons of research, we compiled our findings into a centralized document. This allowed us to review all the information, recognize patterns and trends, and finally come up with a research-backed structure that works for PatternFly.

The new structure

  • Project title: The name of the project is the first thing users see.
  • Brief description: The description is a quick and easy way to communicate the repo’s basic information.
  • Community: This section includes links to PatternFly’s website, its Medium publication, and more. The community section essentially adds a human touch to all this technical stuff.
  • Table of contents: With a table of contents, users can easily see the README file’s sections at a glance and quickly access the areas that are most relevant to them.
  • Links to other README files: When a user lands on the repo’s main README file, they have a high-level view of all the README files in the repo, as well as the ability to easily jump to the file they’re looking for.
  • Setup: This is the basic information on requirements, installation, and usage.
  • Contribution guidelines: One reason PatternFly is so special is because we have a smart and collaborative community of Flyers who contribute to it. To make contribution easy, this section links to a couple other README files that cover how to become a PatternFly contributor, as well as how to contribute to the repo.
  • License: At the very bottom, we show the open source license the project uses.

To see this in action, check out the React repo’s main README file.

A better experience

Also, with a better content experience, users have the resources they need to build better product experiences. So top-notch content can lead to top-notch experiences. How cool is that?

Have a UX story of your own? Send your ideas our way. More writers and fresh perspectives can only make PatternFly’s Medium publication stronger.

PatternFly

A place where UX thrives

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store