RedlineFrom commit-log README
to a docs site developers bookmarked.
Nexus CLI had 3,200 GitHub stars and a README that read like an internal Slack thread. Adoption was flatlining. The install section alone had four contradictory commands.
# nexus-cli
A command-line tool for ████████████ and ████████████████.
## Installation
To install nexus-cli you need to first make sure you have the correct version of node installed (see prerequisites below, note that some systems may require additional configuration). Then run the following command after cloning the repository and navigating to the project root directory:
$ git clone ... && cd nexus && npm install && npm run build && npm link
Note: see CONTRIBUTING.md for more info. Known issues tracked in issues tab.
Last updated: commit 3f8a2c1 — "fix typo in readme"
Catalogued 47 pages. Found 12 dead links, 3 conflicting install guides.
Collapsed 9 nav sections into 3: Get Started, Reference, Guides.
Cut average sentence length from 28 words to 14. Removed 1,400 passive constructions.
Rewrote all 34 code blocks to be copy-pasteable with zero modification.
Deployed with redirects. Zero broken links. Changelog published.
Support tickets tagged #docs-confusion in the 90 days following relaunch. The team stopped triaging questions that the docs now answered.
avg. time-on-page
developer NPS (was 2.1)
full delivery timeline
API docs that made developers
stop opening support tickets.
Aperture's reference docs were technically accurate but practically useless. The auth guide linked to a PDF. Error codes lived in a spreadsheet. Integration time averaged 4.5 days. It needed to be 45 minutes.
# Authentication
Aperture uses OAuth 2.0 with PKCE for authentication. To get started you will need to register an application in the developer portal and obtain your client_id and client_secret. Note that depending on your plan you may or may not have access to certain scopes. See the scopes reference document (link below) for more information about which scopes are available. The token endpoint is located at ████████████████████ and accepts POST requests with the parameters described in the table on page 4 of the API specification PDF.
⚠ Note: The PDF may be outdated. Check Slack #api-updates for latest info.
47 endpoints listed alphabetically
6 resource groups by user intent
Table of 200 codes, no context
Inline, next to each endpoint with fix guidance
Linked to external OAuth spec PDF
Self-contained 3-step guide with runnable cURL
Buried in FAQ section, page 11
Persistent sidebar widget on every endpoint page
Average developer integration time. Measured over 312 new API consumers in the 60 days post-launch.That's 10× faster. Not a rounding error.
developer net promoter score
docs page views / year
Docs that turned
lurkers into contributors.
Vessel had 11,000 stars and 38 active contributors. The CONTRIBUTING.md was last touched two years before I arrived. First-time contributors were opening issues just to ask how to open a PR.
## Contributing
Please read CONTRIBUTING.md before submitting a PR. Make sure to run ████████████████ and ████████████ before pushing. If you have questions, open an issue or ask in ████████████████████.
## License
MIT
(CONTRIBUTING.md was last modified 2 years ago)
# 847 open issues · last release: 14 months ago
“Write to the developer reading at 11pm, not to a committee approving a spec. Use "you" and "your".”
“Every code sample must run without modification. No <YOUR_TOKEN_HERE> placeholders without a link to get the token.”
“Headings are tasks, not topics. "Authentication" → "Authenticate your app in 3 steps".”
“Every error message in the product must have a corresponding docs page. No exceptions.”
New contributors in the 6 months after the docs rewrite. The project went from 38 → 157 active contributors without a single marketing push.
docs page views / year
"how do I contribute?" issues
delivery, fully embedded
The Documentation Playbook
The exact frameworks used across every case study above. 47 pages. No fluff. Free with your email.
The Audit Protocol
A 47-point checklist for diagnosing broken documentation before writing a single word. Covers IA, tone, coverage gaps, and dead ends.
[ ] Navigation: Can a new user find the Quick Start in < 3 clicks?
[ ] Code samples: Do all examples run without modification?
[ ] Error coverage: Does every error code have a resolution path?
[ ] Tone: Count passive constructions. Target: < 10% of sentences.
[ ] ...
The 3-Act Case Study Framework
How to structure any documentation project as a narrative: the mess, the method, and the metric. Used across all three case studies above.
Act I: Document the before state.
→ Screenshot the original. Note every friction point.
Act II: Map the decisions.
→ Each IA change needs a reason. Write it down.
Act III: Measure the after.
→ ...
Developer Voice System
A tone and style framework built specifically for technical documentation. Covers sentence structure, code sample standards, and heading hierarchy.
Rule 1: Write to the developer at 11pm.
Rule 2: Headings are tasks, not topics.
Rule 3: Every code sample must run.
Rule 4: Errors need resolution paths.
Rule 5: ...
Download the Documentation Playbook
One email. No drip sequence. Just the PDF.