10 Tips for Developer Docs

Rule of Documentation #57: "Good docs are as rare as latinum, Treasure them."

Yes we are Star Trek fans... but the point stands, great docs helps teams get 💩 done. And to help you get lots of 💩 done, here are 10 tips for creating stellar documentation:

1. The Four Core

There are four core docs every project (or repository) needs:

• Local Setup Guide

  • How to set up a local dev environment

• Contribution Guidelines

  • How to contribute to the codebase

• Deploy Guide

  • Step-by-step guide on how to deploy the code

• System Diagram

  • A high-level diagram of how the system works

Keep them in /docs with a README linking to them.

2. If You skip everything else, make a system diagram

A system diagram helps new devs grasp how everything connects. Without it, they're lost, mistakes happen, and key knowledge disappears when people leave.

3. Keep docs close to code: write docs in markdown

Docs should live in the repo, versioned with the code. Markdown is simple, easily discoverable, and avoids bloated UI tools.

4. Dev docs without code examples are as useful semicolons in python

No examples? No clue. A solid snippet eliminates ambiguity, reduces frustration, and proves your docs (or code) actually work. Bonus: if they can copy, paste, tweak & execute, your devs will love it.

5. Beware of docs initiatives: start small or else...

Big documentation projects fail quickly, which compounds into "well I guess we don't have docs", "docs are too hard", or "docs aren't important". Instead, make small, incremental updates, starting with the four core docs mentioned above. Ship fast, refine often, celebrate wins.

6. Docs won't write themselves—make tickets, not PR checklists

"Update docs" in a PR checklist or a vague one-liner in acceptance criteria is easily ignored and forgotten. Instead, create dedicated tickets like "Document the new feature" or "Write a setup guide for the new service." If documentation matters, it deserves proper tracking.

7. Stop answering the same Slack questions

Too many repeated Slack questions? That's a sign of bad docs. You wouldn't let customers struggle without support—why do that to your team? Treat internal docs like customer support: create guides, make them self-serve, and reduce friction. Docs first, questions second.

8. Use templates & style guides

Templates ensure consistency & style guides prevent chaos.

Writing good docs isn't just about words, it's about structuring knowledge. Just like writing a solid essay proves deep understanding, well-structured docs force you to clarify how your system truly works. If done right, you don't just document, you gain a deeper mastery of your own architecture. Good docs are designed, not just written.

9. Code comments = Why NOT what

Your code already says what it does. Comments should explain why.

Bad: // Sorts users by last name.

Good: // Sorting by last name to match legacy systems.

10. Reward your team & have some fun

Great docs deserve recognition, just like feature releases. We know documentation is hard, so make it fun by celebrating well-documented updates with shoutouts, rewards, and a little joy, because we should all give a 🦆 about docs!

Happy Documenting 🚀