DEV Community: samuelfatzinger

From Foley Recording to a Usable Sound Library

samuelfatzinger — Mon, 27 Apr 2026 20:20:10 +0000

Turning raw audio into a structured system

I started recording sound effects for my brother’s indie game with a partial plan:

make noises → make them sound good → deliver a successful product

I had the basic idea in place. I needed sound effects, and I knew I could build a library with my own equipment. I anticipated that there would be unknowns, of course, but I was also not starting from whole cloth. I had experience with audio software, but sound effects were new.

At first it was just experimentation. I built a small tabletop isolation booth out of a cardboard box and lined it with the foam acoustic paneling that had come delivered inside of it. I set up a condenser mic by wiring it through a back corner of the box and started recording. Empty bottles, plastic tubes, tapping surfaces, sliding objects, even mouth sounds. Anything that could produce something interesting or usable.

Some of it worked. Some didn’t. Some worked in ways I didn’t expect. I also underestimated how quickly it would become difficult to manage at the pace I was recording.

After a few sessions, I had dozens of files. Sideclick_v.1, Sideclick_v.2, Crush_static_attack_v.1, Crush_static_attack_v.2. Some were trimmed, some weren’t. Some were usable, some weren’t, and it wasn’t always obvious which was which. Finding a specific sound started taking longer than recording it.

At that point, the problem wasn’t sound design anymore. It was organization.

From Recording to Editing

The work quickly split between Audacity and a simple tracking sheet in Google Sheets.

Raw recordings needed a lot of cleanup. I was trimming silence at the beginning and end, cutting out handling noise, and normalizing levels so sounds weren’t all over the place in volume. Some clips needed light compression to bring out quieter details. Others needed to be reduced because they spiked too hard.

I also had to start thinking about how these sounds would actually behave in-game.

Very long clips weren’t useful for most interactions. Short, responsive sounds worked better, especially for UI or repeated actions. That meant cutting clips down to tight lengths, often under a second for simple effects, and only letting longer sounds exist where they made sense.

File type mattered too. WAV files kept the quality intact and were better for editing and integration, while compressed formats like MP3 introduced artifacts that didn’t always hold up well in a game environment. That wasn’t something I thought about at the start, but it became important quickly.

Volume needed consistency as well. If one sound was significantly louder than another, it broke the experience. So instead of just making things “sound good,” I had to start thinking in terms of relative levels, keeping peaks controlled and outputs consistent across the library.

At this point, I wasn’t just editing audio. I was trying to make the files usable.

The Problem Becomes Visible

Even with cleaner files, some issues were still there.

I was using naming conventions, but they didn’t tell you much as an outside user. Or an inside user, for that matter. No clear grouping beyond naming. No way to tell, at a glance, what something was or where it belonged in terms of its use or purpose. Some files had been manipulated enough that slap-hit_v.2 and slap-hit_v.8 sounded completely different. Without the descriptive name, it would be impossible to tell that these sounds came from the same source.

The bigger issue was differentiation. My naming system was based on versions of a single source sound, but those versions could drift far enough apart that the names alone could stop being useful.

That’s when more extensive structure started to show up, not because I planned it, but because I needed it.

Building a Structure into the Work

The first organizational state was naming.

Instead of arbitrary file names, I started using simple patterns. The description of sound first, then its iteration. I needed to describe the sound first, not its potential use. Usage could be categorized later, but the sound itself was the stable reference point. Something like Laser_celery_v.4 or Zhuzh_v.7. Nothing complex, just enough to make the file understandable without opening it.

Sounds were labeled in a separate column by how they were created (Foley, vocalization, vocal effect, etc.). This made it easier to browse and also forced me to think about how each sound would actually be used. For instance, different character wordless vocalizations could potentially come from different sound sources. If I didn’t know where something belonged, I marked it in a separate column for potential use so I knew it wasn’t clearly defined yet.

From there, I started defining what “done” meant.

A usable sound needed to be trimmed, cleaned, and consistent in volume. It needed to be the right length for its purpose. It needed to be in the right format. Anything that didn’t meet those criteria wasn’t ready, even if it sounded good.

I also included details about the sound in terms of length, as well as a short description such as “cartoonish” or “haunting”. These descriptors were tracked in their own column, alongside another column noting how each variation changed from the previous one. For example, Wowow_v.1 contained four long pulses in mid-range, while Wowow_v.2 increased speed but still contained all four pulses, which were now shorter and higher pitched.

That led naturally into a simple process:

record → edit → trim → normalize → name → categorize → store → export

Nothing formal, but repeatable, with each entry including a file name, category, and notes on its usage. It became both a label and a reference point. If something needed to be updated or replaced, I knew where it lived and how it was being used.

Turning it into a System

Once the system existed, the process gained momentum and clarity. Organization frees up creativity. Systems make it easier to see both what you have and what’s missing. Using accurate naming and descriptions as you go, as part of your process, rather than after the fact, allows you more freedom to create and explore because everything else is already in place.

A shared folder structure made sense, with categories reflected in directories. Files lived where you expected them to be. Naming made them readable. The structure made them findable. Nothing complex. At that point, it stopped feeling like a collection of files and started operating like a system.

Not all of this was completely planned up front. It took a few iterations to understand what was needed. I didn’t start with requirements or a structure. I started by recording sounds and figuring things out as I went. The structure appeared because the work demanded it. Naming, categorization, and documentation weren’t separate steps. They were responses to problems that showed up along the way.

And once they were in place, the work changed. Finding sounds became faster. Using them became easier. Adding new ones didn’t create more chaos. The system held together.

What started as a creative exercise turned into something more structured than I expected. Not because I set out to design a system, but because I needed the work to be usable. The moment the number of files grew past what I could keep track of mentally, writing and structure became necessary.

A lot of work doesn’t begin with clear requirements or defined systems. It begins in a loose, experimental state, and structure comes later, usually in response to scale or confusion.

In this case, it came from trying to make a growing set of sound files something that could actually be used. And once it did, the work became easier.

From Noise to Signal: Finding README Gaps at Scale

samuelfatzinger — Mon, 20 Apr 2026 14:55:17 +0000

Automating the search for under-documented GitHub projects

I kept running into the same problem while browsing GitHub for repositories that I could confidently contribute to. Plenty of projects looked interesting, but their README files were missing, thin, or unclear. Finding good candidates for documentation work meant opening repositories one by one and making a quick judgment. It worked well enough, but it didn’t scale. It meant sorting through a large number of non-candidates first.

So I built a small CLI tool to make that process more consistent and to better manage my own time (and sanity).

The Problem

There’s no simple way to surface weak README files across many repositories. The process tends to rely on manual searching and quick impressions, which makes it difficult to explain why one project feels worth working on while another doesn’t. Over time, that lack of consistency becomes a problem. It’s harder to compare repositories, and even harder to prioritize where your effort would actually make a difference. It’s an inefficient and time-consuming way to sort through work, and both are worth conserving.

What I Needed

I wasn’t trying to solve documentation quality in a general sense. I just wanted a way to move a little faster without losing clarity. That meant being able to surface likely problem repositories quickly, understand what was missing without opening each one, and apply the same lens across everything I looked at. Something simple, repeatable, and easy to manage. A time-saver that actually saves time. I needed the tool to not only work, but to work well.

Turning Judgment into Signals

The shift came from taking something instinctive and giving it a bit of structure.

Instead of relying on a quick read and a gut feeling, I started asking what weak READMEs tend to have in common. In most cases, it wasn’t anything subtle. Very low word count usually meant a lack of depth. Missing sections like installation or usage made the project harder to approach. A lack of headings often meant the content wasn’t organized in a way that helped the reader.

None of these signals are perfect on their own. Some projects are intentionally minimal, and some document things elsewhere, so there are still cases where the tool works as designed, but the result isn’t a strong candidate. But taken together, these signals form a pattern that’s useful enough to work with. Once that pattern exists, it becomes easy to apply consistently.

How I Built It

The tool follows a straightforward flow. It begins by searching GitHub repositories using a query, then retrieves README files through the GitHub API. Once the content is decoded, it runs a set of simple checks against it.

If you want to try it yourself: readme-radar on GitHub

Those checks are intentionally basic. Word count provides a rough sense of depth. Section detection looks for the presence of common elements like installation or usage. A quick pass over the structure looks for headings and general organization. From there, the tool assigns issue flags and a rough score.

The results are sorted so that weaker candidates rise to the top. The goal isn’t to produce a perfect ranking, but to make the output easy to scan. Instead of opening repository after repository, you can quickly see which ones are likely to need attention.

Over time, I added a few small improvements. Filtering made it easier to remove strong candidates from the results. Summary counts provided a quick sense of what issues were most common in a given scan. An optional JSON output made it possible to reuse the results elsewhere. None of these additions are complex, but they reinforce the same idea: apply a consistent set of checks, then make the results usable.

What Changed

Before building this, the process was mostly reactive. I would browse, click into a repository, scan the README, and decide in the moment whether it needed work.

Afterward, the process became more intentional. Instead of looking for anything, I could look for specific types of problems. That small shift changed the workflow from browsing to targeting. It also made the decision-making process easier to explain, because it was based on defined signals rather than a vague sense of quality.

Outcome

The tool reduced the time spent searching for documentation opportunities and made the process more consistent. It started as a small utility to speed up a repetitive task, but it ended up changing how I evaluate documentation in general. More importantly, it clarified what I was actually evaluating when I looked at a README.

Even without the tool, that clarity sticks. A vague problem becomes easier to work with once it’s defined, even loosely. From there, it becomes something you can repeat and refine over time.

The tool itself is small. The thinking behind it is what scales.

The Case for Tiny Tools in Workflows

samuelfatzinger — Fri, 03 Apr 2026 18:08:00 +0000

Using simple tools like snippets to write faster and stay consistent

A lot of documentation work repeats itself. Setup steps. Warning blocks. API examples. Environment variables. If you’re like me, you have notes and prompts that show up in project after project.

The usual solution is copying from something older. A previous README, a doc you wrote last month, a scratch file you keep around. Your left pinky and index finger are noticeably more muscular than your right, and the text on your Ctrl key is worn down from use.

It works, but it can get cluttered quickly as versions start to evolve. Wording and phrasing drift based on the day. Formatting changes. Sometimes you fix something in one place and forget about others.

None of this is a big problem on its own. It just adds small bits of effort every time you sit down to write.

That’s where tiny tools start to make sense.

The Limits of Copy/Cut/Paste

Copy and paste is fast, but it depends on memory. You have to remember where the good version lives. Sometimes you search through repos or digital scrap paper in Google Docs. You may find yourself opening three different similarly named files just to find the one block you want. I tend to keep around 20 open tabs in Notepad at any given time.

Even then, when you find it, you usually tweak it. A word, a phrase, a sentence changes. A heading moves. An indentation shifts. Over time you end up with five slightly different versions of the same thing.

This isn’t dramatic. It just makes writing feel less steady than it should. You spend time looking for or deciding between things you’ve already written, and the results slowly lose consistency. Flow state usually doesn’t survive this.

What Tiny Tools Do Well

Small single-purpose tools help in a quiet way. They don’t try to manage everything, they just hold onto the pieces you reuse the most or perform a routine function. They open quickly and they do one thing. They fit into whatever workflow you already have. With small tools there’s no system to maintain and nothing new to learn. It’s all about efficiency and staying in flow.

We’ve had these tools for decades to the point that they are commonplace (spell check) while others have gone by the wayside (Clippy). As technology increases, so do the number and efficacy of the tools that help us use it. Technology for our technology.

The idea sounds a little odd at first. More tools should mean more complexity. But it often works better when those tools stay small. Kind of like the square-cube law. As things get bigger, volume grows faster than surface area, and smaller objects end up with more surface area relative to their size. That’s why small pieces cool faster and can sometimes be structurally stronger. If we’re talking about work, one giant program can be more oppressive and energy-draining than a system of smaller ones.

Some Examples

Prompt managers, or snippet tools, are a good example of this, as anyone who works with an agent or LLM knows. You can store blocks you use often and reuse them when needed: summarization, setup instructions, example commands, formatting templates. Pretty much anything, really. It’s simple, but that’s the point. The value comes from not having to think about it.

I built a small web app called SnipDeck for this. The goal wasn’t to create a big platform. It was just a fast place to store and reuse common writing blocks. Something you can open, copy from, and close.

Formatting tools are another example. Cleaning up markdown, aligning tables, fixing indentation, converting pasted text into something readable. These are quick edits, but they show up constantly.

Previewing is another. A markdown previewer or a JSON viewer that lets you check output without switching tools. You open it, paste, confirm, and move on.

Some tools just generate structure: a basic README starter, an API example template, a CLI command builder. They don’t try to understand the project. They just give you a clean starting point.

There are plenty of others, of course, from conversion tools to command builders to exporters. The point is that rather than having one bloated tool, you have a customizable toolbox of smaller, less complex tools. They just remove small bits of repeated work.

Why This Approach Holds Up

Individually, none of these tools are especially impressive, and most of them handle tasks you could do manually in a few seconds. The value comes from how often those seconds show up and how repetitive documentation work tends to be. The same structures appear across projects, the same examples get rewritten, and the same formatting cleanup happens over and over. Tiny tools do not change the work itself so much as make it easier to do consistently, which keeps writing steady and reduces the small decisions that interrupt the process.

This is where the small-tool approach starts to add up. Instead of digging through old files, you reuse text that is already clean. Instead of fixing formatting after the fact, it starts in a usable state. Instead of remembering commands or structure, you generate a reasonable starting point and adjust from there. None of this is dramatic, but together it smooths out the edges of everyday writing and makes it easier to stay focused on the explanation rather than the mechanics.

Staying in Rhythm

In that sense, the appeal is similar to the earlier comparison. One large tool tries to handle everything at once, which can add weight and complexity even when you only need a small piece of it. A collection of smaller tools supports the work as it happens, each one handling a narrow task and then getting out of the way. They sit alongside your editor rather than on top of it, and over time they reduce repetition without becoming another system that needs attention.

Tiny tools address these workflow issues directly, and the cumulative effect is that writing and building become more predictable and consistent without disrupting your rhythm.

The UX of README Files

samuelfatzinger — Tue, 31 Mar 2026 16:38:09 +0000

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.

Turning Documentation Instinct Into a CLI Tool for Finding README Gaps

samuelfatzinger — Tue, 24 Mar 2026 16:51:01 +0000

Search and Scroll

As mentioned in my previous post, contributing documentation to open source can be daunting for a technical writer trying to get started. Something I didn’t mention was the physical slog that can also be discouraging, even for writers who are already comfortable contributing. By slog, I don’t mean the work of editing, reorganizing, or pushing commits. I’m talking about the search and scroll for suitable repositories.

You open repo after repo, scan the README, decide it’s not a good fit, and move on. It can be monotonous, tedious, and frustratingly mind-numbing. What makes this even harder for non-coders is that suitability narrows the scope further. GitHub is built around code, and finding projects that benefit from documentation work takes time.

There are several excellent sites designed to help new contributors get their foot in the door, such as:

firsttimersonly.com,
First Contributions, and
goodfirstissue.dev.

These types of guides also help contributors navigate searches and tags like “documentation” and “good first issue.”

As a new contributor, I used these tags and search parameters to find repositories in need of documentation updates, only to discover that the content didn’t always need repair or that the issue required more technical knowledge than expected. I know from experience how disheartening it can be to want to contribute but spend limited free time scrolling through search screens, wearing down a mouse wheel, and clicking “Next Page.”

There Has to Be a Better Way

One morning last week I sat staring at my screen, convincing myself that time spent sipping coffee wasn’t wasted as my vision unfocused and drifted toward the wall. I put myself to work, but while typing into GitHub’s search field, I thought: there has got to be a better way to do this.

Third-party sites are useful, but from my experience they are often geared toward first-time coders or people looking for specific projects. YMMV. I wanted something that would make my searches more efficient so I could spend more time writing and less time scrolling.

I started wondering if I could build a tool to automate the search so I could spend more time contributing and less time looking.

So I did.

readme-radar

The result is readme-radar, a CLI tool that searches GitHub for repositories with weak or missing README files that could benefit from documentation work. The project is available here: readme-radar on GitHub

The premise is simple:

fetch repos → evaluate READMEs → rank candidates → show results

The goal is to reduce manual scanning and identify documentation opportunities quickly. It looks like this:

Input

python readme_radar.py "python cli" --show 1 --compact

Output

readme-radar
============
Query: python cli
Scanned: 30
Flagged: 5
Shown: 1
Strong candidates: 1
Good candidates: 0

Top issues:
2 - README under 100 words
1 - Missing README

1. STRONG CANDIDATE | user/repo | stars: 12 | score: 92 | README under 100 words
   https://github.com/user/repo
   other issues:
   - Missing Installation section
   - Missing Usage section

Scoring and Ranking

The most important pieces here are the search and ranking metrics. I’m only looking for repository candidates I can realistically contribute to, which means building a scoring model that fits my needs and capabilities.

The ratings are based on factors like whether a README exists, whether it’s substantial, missing sections, and overall brevity. These are key indicators of what can make a README weak or in need of improvement.

Often what I have found is that weak READMEs work more as placeholders that never get revisited. They are short and lack specificity, or are sometimes filled with repetitive content meant to take up space, sometimes with multiple, redundant, numerous, excessive repetitions for the sake of filling space. Both of these are great candidates for improved documentation.

To be clear, just because a README is short is NOT automatically an indication that it is weak. Sometimes short fits the bill. I have contributed to repos that had short READMEs that needed a few language edits and nothing more. But, brief can be bad if it is brief for lacking what’s necessary for the user.

Weak READMEs are usually missing headers and sections as well, either as a continuation of the previously stated causes, or because the README is a wall of text without any markdown at all. These can be flagged by readme-radar and often make excellent candidates. Lack of sections or proper markdown can be an organization issue rather than missing content, and those feel great to contribute to because the author knew what they needed to include, you’re just there to help tidy up a little bit.

The tool’s candidate results are ranked so the weakest candidates, which are often the best fit for documentation work, appear at the top, and then descend in order according to the scoring metrics. This lets the user see the strongest candidates first with little to no scrolling.

The compact output prints key metrics on the top lines to improve scannability even more. Rather than reading dozens or even hundreds of READMEs, I may only need to look at a handful to decide what’s worth opening.

The tool also supports JSON export. This makes it possible to save candidate lists from a strong search result or build workflows around specific contribution sessions. Instead of picking through repositories one at a time, the tool makes it easier to build a queue and track documentation opportunities.

Designed for Writers

Engineers start with a focus on code quality. Technical writers start with a focus on connectivity. It’s all about the entry point: What is this? Why is it useful to me? How do I use it? These are questions that echo in the ravine between engineer and end user. A technical writer’s job is to build a bridge across that gap. Sometimes there’s just a rope flung across that gap. It’s staked down at each end, sagging in the middle, and a bit frayed. It works, but it’s not inviting. It’s not exactly safe to walk across either. A technical writer sees that rope and thinks about adding a few more, braiding them together, and putting in better stakes.

When I first started contributing, I wanted to make every bridge I came across a marvel of civil engineering. But that’s not necessary in most cases. All I was doing was frustrating myself by wanting to do more. I was gilding the lily. Documentation, cliché or not, really is a “less is more” kind of work.

Part of the problem for me was that I was spending so much time searching for something to work on that when I finally found a candidate I wanted to validate my time spent searching by doing too much. What readme-radar has helped me with is cutting that work anxiety because I know there are other readily available projects to contribute to. It’s easy to find a project, do the work, and move on to the next one. It’s a tool built specifically with writers in mind by streamlining the workflow and facilitating efficiency during contribution sessions.

Finding Friction

I kept running into the same friction: finding something worth improving took longer than the improvement itself. It should be about making things easier for the user, and in this case, that user was me.

Building a tool like this changed how I started thinking about my own portfolio of work. I had always thought of myself as separate from coding, despite having some knowledge and experience. I imagined open source as a world populated by engineers, with technical writers working somewhere on the periphery.

This project shifted that perspective. It showed me that there isn’t just overlap, but an interweaving of skills. Documentation, tooling, and development all support each other.

readme-radar started as a way to reduce the search and scroll. It ended up reinforcing something broader: technical writers don’t just improve documentation. Sometimes they build the tools that make better documentation easier to find.

If you’ve found good ways to identify documentation gaps in open source, I’d be interested to hear your approach.

Feedback on readme-radar is welcome as well.

You Don’t Need to Code to Contribute to Open Source

samuelfatzinger — Sat, 21 Mar 2026 18:54:15 +0000

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.