I maintain 20+ open-source packages. Every one of them needs documentation. And every time I start a new project, I solve the same problems — folder structure, linting rules, release notes, badge standards.
claude-docs was supposed to fix that. But until today, it was just a set of guidelines and a slash command. Helpful, not enough.
So I blocked out a day to turn it into a proper toolchain. 8 commits, 20 files changed, +2,083 / -449 lines. Here's the before and after.
Documentation Guidelines
Before: Abstract rules about how docs should look. You read them, nodded, then did your own thing anyway.
After: Rewritten from scratch with concrete examples for 5 project types — Laravel packages, APIs, full-stack apps, CLI tools, and SDKs. Numbered folder conventions, progressive detail structure, ADR support, MermaidJS diagrams. Over 700 lines changed in the first commit alone.
The goal: if you can't figure out how to structure your docs after reading the guidelines, that's a bug.
Markdown Linting
Before: markdownlint was configured, but you had to run it file by file. Most of the time, people just skipped it.
After: One script, one command. lint.sh finds all markdown files, auto-detects your config, and lints everything in one pass. Add --fix to auto-correct.
~/.claude/lint.sh # lint everything
~/.claude/lint.sh --fix # lint & auto-fix
If linting takes effort, nobody lints. Now it doesn't.
Release Notes
Before: Manual. Copy commits from git log, reformat into markdown, paste into CHANGELOG. Every. Single. Time.
After: release-note.sh — a 300+ line script that parses your git log, categorizes commits by conventional prefixes, and generates structured markdown with summary tables and contributor lists.
~/.claude/release-note.sh # today's release note
~/.claude/release-note.sh --tldr # summary version
~/.claude/release-note.sh --since "1 week ago" # custom date range
~/.claude/release-note.sh --output CHANGELOG.md # write to file
This one went through three iterations in a single session — build, refactor, extend. The first version showed me what the second version needed. That's the natural rhythm for tooling work.
Badge Standards
Before: Some projects had badges, some didn't. No consistency.
After: Mandatory version and license badges for every project README. Copy-paste templates for 10 package registries (Packagist, npm, PyPI, crates.io, and more). Badge compliance tracked in the /docs health report.
Badges are the first thing people see on your repo. They signal you care. Making the standard easy to follow is what makes people actually follow it.
Project Auto-Detection
Before: PHP and Node only.
After: Supports Python, Ruby, Rust, Go, .NET, Java, Dart/Flutter, and Elixir. Run /docs scaffold <type> and get the right structure for your stack.
What /docs Can Do Now
After today's update, here's everything available under the /docs slash command in Claude Code:
| Command | What It Does |
|---|---|
/docs | Create new documentation structure (auto-detects your project type) |
/docs reorganize | Reorganize existing docs into the numbered standard |
/docs validate | Validate against standards and report issues |
/docs update-toc | Update all README.md table of contents |
/docs health | Generate documentation health report with badge compliance |
/docs scaffold <type> | Scaffold from template: laravel, api, cli, sdk, fullstack |
/docs release-note | Generate full release note from today's git log |
/docs release-note --tldr | Generate summary release note |
One command to rule them all. Pick what you need.
The Full Picture
One install command gets you everything:
curl -fsSL https://raw.githubusercontent.com/nasrulhazim/claude-docs/main/install.sh | bash
| What You Get | What It Does |
|---|---|
| Guidelines | Concrete examples for 5 project types |
lint.sh | Batch markdown linting with auto-fix |
release-note.sh | Git log → structured release notes |
/docs command | Scaffold, validate, health report, auto-detect |
| Badge templates | 10 registries, 13 project types |
Why This Matters
I'm a solo founder running Cleanique Coders. No docs team, no technical writer. What I have is tooling that enforces standards so I don't have to remember them.
Every hour spent on this saves ten hours of "how did we do docs in that project?" across the next year. If you maintain multiple repos — especially alone — standardize the boring stuff first.
The repo is open source. Take it, use it, tell me what's missing.