DEV Community: samuelfatzinger

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.