Open Source Docs: The Contribution Nobody Wants to Write (But Everyone Desperately Needs) 📖🔥
Open Source Docs: The Contribution Nobody Wants to Write (But Everyone Desperately Needs) 📖🔥
Confession: I once spent 45 minutes trying to install an open source security tool with 4,000 GitHub stars.
The README said: "Install and run." That was it. Three words. For a tool with 14 dependencies, two conflicting Python versions, and a config file with 60 undocumented fields.
I eventually got it working. Via Stack Overflow, a 3-year-old blog post, and what can only be described as pure spite. 😤
That experience changed how I think about open source. Not the code. The docs.
The Uncomfortable Truth About Open Source Documentation 🤦
As a full-time developer who contributes to open source, I've watched good projects die slow, sad deaths — not because of bad code, but because of docs that read like they were written by someone who'd already forgotten how they built the thing.
Here's the pattern:
Month 1: Developer builds cool tool
Month 2: Developer puts it on GitHub
Month 2.5: Developer writes README at 2am
(after 6 energy drinks)
Month 3: Real users show up
Month 3.1: "Why doesn't this work?"
Month 3.2: "What does this flag do?"
Month 3.3: "Is this project dead?"
Month 4: Developer exhausted by questions,
stops responding
Month 5: Project is effectively dead 💀
The code worked. The docs killed it.
Balancing work and open source taught me this: the bottleneck in most projects isn't features or bug fixes. It's the 30-second README moment where someone decides "I get this" or "close tab."
Why Developers Hate Writing Docs (And Why That's Wrong) 🧠
I get it. Docs feel like busywork. You've built something cool, you understand how it works, why write it down?
Reason #1: The Curse of Knowledge
The moment you build something, you can never un-know it. That config option that took you 3 days to figure out? You've already internalized it. Writing it down feels pointless because obviously it works that way.
To everyone else: it's a black box.
Reason #2: Docs don't ship features
When your todo list has "add authentication" and "document installation," you're picking authentication. Every time. That's rational. But docs compound — an hour of writing saves thousands of hours of user confusion.
Reason #3: Nobody will read them anyway
Actually, let me stop you right there:
GitHub truth bomb:
- 67% of developers check docs BEFORE trying a project
- A project without clear docs gets 3x fewer contributions
- Good docs = more stars, issues, and PRs
- Bad docs = "is this abandoned?" issues
In the security community, this is especially brutal. I've seen excellent security tools with zero adoption because the README assumed you already knew how to use them. Meanwhile mediocre tools with great docs get adopted everywhere. Docs ARE the product for your users.
The Moment Docs Saved My Sanity 💡
About two years ago, I contributed a security scanning feature to a PHP package. The PR got merged. I was thrilled. Then I watched what happened.
Three weeks later: 7 new issues. All of them: "How do I use this new feature?"
I hadn't written docs. The maintainer hadn't either. We'd both assumed it was obvious.
I spent a Friday afternoon writing a proper guide. Clear examples. Common gotchas. Config options explained in plain English.
The issues stopped. Completely.
The same feature that generated 7 confused issues in 3 weeks generated ZERO in the next 3 months.
That Friday afternoon was worth more than the code contribution itself.
What "Good Docs" Actually Looks Like 🎯
Here's the thing: most docs fail in predictable ways. Let me show you.
The README That Kills Projects ❌
# CoolTool
A tool for doing things with data.
## Installation
See the docs.
## Usage
Run the binary with the appropriate flags.
## Contributing
PRs welcome!
What flags?? What docs?? WHICH BINARY?? 😭
The README That Builds Communities ✅
# CoolTool — Process JSON files 10x faster 🚀
Turn this:
$ cat huge-file.json | some-slow-tool
[waited 45 seconds]
Into this:
$ cooltool huge-file.json
Done in 4 seconds ⚡
## Install in 30 seconds
# macOS
brew install cooltool
# Linux
curl -fsSL https://cooltool.dev/install.sh | bash
# Windows
winget install cooltool
## Quick Start
$ cooltool input.json # Process a file
$ cooltool input.json -o out/ # Save output
$ cooltool --help # All options
## Common Use Cases
**Extract all users from a large JSON:**
$ cooltool --filter "users" big-data.json
**Process multiple files:**
$ cooltool *.json --merge
**Stuck? Common errors explained:** [TROUBLESHOOTING.md]
Feel the difference? First README creates confusion and issues. Second README creates users and stars.
The Types of Docs Contributions (Pick Your Weapon) 🔧
Here's where it gets interesting. "Write docs" sounds monolithic but it's actually a menu of contribution types:
1. The README Rescue 🚑
The quickest win. Find a project you use, open the README, identify where you got confused when you first started, and fix it.
Good first issue: "I was confused by X when I first started. Here's a clearer explanation."
No maintainer will ever reject that. I've had README fixes merged in under an hour.
2. The Example Whisperer 💬
Code examples age poorly. They reference old APIs, use deprecated syntax, or just... don't work anymore.
# Find projects where examples are broken:
# Open the README
# Copy an example
# Run it
# Did it work? If not, you have a contribution!
Balancing work and open source taught me this: I keep a "docs debt" habit. Every time I use an open source tool and Google something that should be in the docs, I note it. Then I submit a PR. 30 minutes of writing, contribution merged, karma points earned.
3. The Troubleshooting Archaeologist 🦴
Dig through old GitHub issues. Find the questions that get asked over and over. Write a TROUBLESHOOTING.md or FAQ that answers them.
This is pure gold for maintainers. They're tired of answering the same 5 questions. You're literally taking future support burden off their plate.
High-value patterns to look for:
- Issues with titles like "Error: ..." repeated multiple times
- Closed issues with "it was my config" as the answer
- Long comment threads on simple questions
4. The API Doc Hero 📋
If a project has functions or config options with no explanation — describe them! You don't need to understand the implementation. You need to use the function, observe what it does, and write that down.
// BEFORE (in the codebase, no docs):
public function process($data, $flags = 0) { ... }
// AFTER (docs you wrote):
/**
* Process data through the pipeline.
*
* @param array $data Input data to process
* @param int $flags Bitfield of PROCESS_* constants
* PROCESS_STRICT: fail on first error (default: 0)
* PROCESS_ASYNC: run in background
* @return ProcessResult
*
* @example
* $result = $pipeline->process($userData, PROCESS_STRICT);
*/
In the security community, we take this seriously. A security tool with unclear docs isn't just unusable — it's dangerous. People misconfigure it and think they're protected. Good docs are a security feature.
My Actual Workflow for Doc Contributions 💻
Here's exactly what I do when I want to contribute docs to a project:
Step 1: Use the project for real
# Clone and try to set it up from scratch
# As a fresh user, no prior knowledge
git clone https://github.com/some/project
cat README.md
# Start following instructions
# Note every moment of confusion
Step 2: Keep a confusion log
Confusion Log - ProjectName
===========================
- Line 12: "run the server" — which command?
- Config file: 8 options, none explained
- "advanced mode" mentioned but not defined
- Windows instructions missing entirely
- Error message "ENOENT" not explained
Every confusion = one potential docs contribution.
Step 3: Fix ONE thing at a time
Resist the urge to rewrite everything. Pick the most confusing part:
git checkout -b docs/clarify-installation-windows
# Make your changes
# Clear, focused, single improvement
Step 4: PR with context
## What this changes
Installation steps were missing Windows-specific instructions,
causing users to hit "ENOENT" errors (see issue #234, #256, #289).
Added Windows instructions with the exact powershell command
and a note about needing admin privileges.
Tested on Windows 11 with PowerShell 7.
Maintainer reaction: instant merge.
Projects That NEED Your Docs Help Right Now 👀
Looking for somewhere to start? These types of projects always have docs gaps:
🔒 Security Tools — Tools like Semgrep, Trivy, and OSV Scanner have incredible codebases but docs that assume deep security knowledge. If you can translate technical concepts into plain English, security projects desperately need you.
🔧 CLI Tools — Any CLI tool with more than 10 flags probably has flags that aren't documented well. Run --help and find options with cryptic one-liners. Then write better explanations.
📦 Package Ecosystems — Laravel packages, npm modules, pip libraries. Check if the package README shows realistic examples with actual expected outputs. If not: opportunity.
🌍 Internationalization — Big projects have English docs. Non-English communities are underserved. If you're bilingual, translating docs is one of the highest-impact contributions you can make.
🧩 Integrations — "How do I use this with Laravel/Express/Django?" questions flood issues in many projects. Writing integration guides closes entire categories of issues.
The Tools That Make Doc Writing Easier 🛠️
Because if you're going to write docs, write them efficiently:
For Markdown:
# Preview locally before submitting
npx serve . # Serves the directory, previews markdown
# Check for broken links
npx markdown-link-check README.md
# Lint your markdown
npx markdownlint README.md
For finding what's missing:
# Find all TODO/FIXME comments in docs
grep -r "TODO\|FIXME\|TBD" docs/
# Find undocumented functions (PHP example)
grep -r "public function" src/ | grep -v "/**"
For screenshots and demos:
Asciinema for terminal recordings. Free, embeds in README, maintainers love it.
# Record your terminal
asciinema rec demo.cast
# Upload and get a markdown-embeddable link
asciinema upload demo.cast
The Secret Superpower of Doc Contributors 🌟
Here's something I've learned after years of contributing: doc contributors get promoted to maintainers faster than code contributors.
This sounds backwards. But think about it from the maintainer's perspective.
A code contributor: submits PRs occasionally. You review their code, merge or reject.
A doc contributor: demonstrates they deeply UNDERSTAND the project. They know what users struggle with. They communicate clearly. They're already doing part of the maintainer's job.
I've been invited as co-maintainer on three different projects. Two of those invitations came after doc contributions, not code contributions.
As a full-time developer who contributes to open source, I'd tell junior devs this: if you want to build open source credibility fast, write docs. Code PRs compete with everyone. Docs PRs are in their own category.
The "Low Effort, High Impact" Doc Moves 🎯
If you're pressed for time, these take 15 minutes or less:
Quick wins:
✅ Fix a broken example that no longer runs
✅ Add the actual expected output to a code example
✅ Clarify one ambiguous config option
✅ Add a "Prerequisites" section if missing
✅ Fix a typo (yes, even this counts!)
✅ Add a link to the official site from the README
✅ Update a badge that shows wrong build status
✅ Add "tested on [version]" notes to examples
Every one of these has a good chance of getting merged same day.
What Maintainers Actually Say About Doc PRs 💬
I asked around in communities I'm part of. Here's what maintainers say about doc contributions:
"A good doc PR is worth 10 feature PRs to me. Features I can build. Knowing what confuses users? That's gold."
"I merged a docs PR in 4 minutes. It took longer to write the merge commit."
"My biggest regret is not prioritizing docs early. We lost contributors who couldn't figure out how to set up the dev environment."
"Typo fixes get a bad rap but they signal someone actually read the thing. That matters."
TL;DR 💡
- Docs are the number one reason good projects fail to gain adoption
- Writing docs is one of the highest-impact OSS contributions you can make
- It's beginner-friendly: you don't need to understand the internals
- Find what confused YOU when you started, and fix that
- Small, focused doc PRs get merged same-day more often than code PRs
- Doc contributors often get invited as maintainers
- Start with a confusion log: note every moment of "wait, what?" when using a tool
Your challenge this week: Pick one open source tool you use. Find one thing the docs didn't explain well. Submit a PR fixing it.
Takes 30 minutes. Helps everyone who comes after you. Gets you a GitHub contribution square. Builds maintainer trust.
Write the docs you wish existed when you were confused. That's all. 📖✨
Got a docs PR you're proud of? I'd love to see it — find me on LinkedIn or GitHub.
The open source world runs on code. But it grows on documentation. 🌍