A new look for PatternFly’s React README files
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?
As a UX Content Strategist, I’ve been looking through various PatternFly content channels — technical documentation, site content, social media, blogs, and more — but the one content type that really stood out was our README documentation. I was impressed (and still am!) at how much useful information is out there in our README files.
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
Now came the research process, which consisted of three phases: collaboration, discovery, and learning.
Collaboration
The best content is built on collaboration. Diverse ideas, skills, and abilities yield better content results — the information has more interesting facets and creative angles.
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
Maybe you’re wondering, Why the React repo?
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
The final phase in the research process was learning. This was certainly the most rewarding and insightful part of the project.
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
So without further ado, here’s the new structure for the PatternFly React repo’s main README file. This structure will also be applied to the other README files in the repo, so stay tuned!
- 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
Our users deserve the best of everything PatternFly has to offer. With revamped README files, we hope all users can navigate the documentation and find what they need easily — and have some fun while doing so.
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.
