A technical writer’s path into open source documentation
Looking for a Way In
When I first started getting into open source documentation, I was a bit unsure of where to get started. I’m not an engineer by trade or craft, and that’s the majority of what goes on in these open source spaces. What I do like is writing, contributing to projects, and making things easier to understand.
I was looking through projects on GitHub trying to find things I could help out with. What I noticed is that some READMEs looked incoherent while others looked easy to read and move through. Tidiness isn’t everything, but it does help someone navigate through a document. Organization is paramount for good documentation.
What I Look for in READMEs
Here’s where I come in. I read through READMEs not just to see what’s working, but what could work better. The components are there, but are they in the right place? Can someone skim, scan, and move through the document without getting lost? If I put two lists together, do they make sense? Maybe they would under different headings. What if I split them under adjacent subheadings? A reader may only need one of them, and separating them may save time and improve focus. It’s all about making things as easy as possible. A good document is one that someone doesn’t even notice. It’s often the bad that sticks out, not the good. Aim for that silence.
Another thing I noticed is that information familiar to the author was not always clear to others. Directions were sometimes skipped altogether, and bash commands were placed alone on the next line like a kid in Little League sitting in left field picking at grass. The broader lesson is that the work makes more sense to the creator than it does to people encountering it for the first time. Some writers make too many assumptions about their readers’ knowledge base. While this can create efficiency by shortcutting, it can also lead to confusion and ultimately decrease efficiency. Shortcutting language is natural in jargon-heavy spaces, but there’s a tendency in fast-moving environments like code to push this too far. Saving time in the writing often creates more time in the reading. Good documentation does the opposite. It puts the effort up front so the reader doesn’t have to.
Good organization is about being flexible. Don’t just edit, explain why. These kinds of changes don’t require deep technical knowledge. It’s about understanding how someone engages with the information and identifying friction. For the most part, if something feels out of place, it probably is. Just make sure you explain the what and the why when submitting your pull request. Editors can make assumptions about their authors as much as authors can make assumptions about their readers. If a change makes sense to you, it doesn’t mean the original author will immediately understand why. The work you do for a reader also applies to communicating your edits with the author. A good editor is a giver above all else.
Small Changes Matter
One README I worked on went straight from the title to setup instructions without explaining what the tool was or what it was meant to do. I added a simple overview section that explained what the tool was and what to expect. I also included a brief prerequisites section that clarified what was needed for the tool to function. Small sections like these can greatly improve someone’s ability to understand and use a project without forcing readers to rely on assumptions.
Sometimes it’s as simple as grammar and spelling. I’ve worked on READMEs that were otherwise well-organized but lacked a writer’s touch. And these things matter. Surface-level edits can go a long way in making someone confident in a project’s ability to deliver as promised. It may not seem like you’re doing much at first, but it’s valuable. And keep in mind that everyone needs outside attention on their work no matter what it is. Mistakes don’t just happen, they happen frequently. Our brains overlook small errors like spelling and grammar mistakes because they cost too much energy relative to higher levels of content. Even best-selling authors like Stephen King, who seem to publish a novel a week, still use editors and proofreaders. It’s work that everyone needs done, so if you see it, fix it.
For technical writers looking for a way in but daunted by a lack of code knowledge, I say dive in. Start with clarity. Look for missing context, confusing structure, or assumptions about the reader. These are small changes, but they matter. Documentation improves one edit at a time, and open source projects benefit from anyone willing to make things easier to understand.
If you're a technical writer without a coding background, whether you're just starting or already contributing, I’d be interested to hear your approach.
Top comments (0)