🧠 We Want Better Resources for Knowledge Sharing

A recurring theme in our developer experience survey: we need better documentation. It’s not a new complaint—but it’s one we keep hearing for a reason. Documentation remains one of the most valuable (and most neglected) resources in any engineering organization.

I’ll be honest: I’ve always seen documentation as a luxury. It’s something only teams that already have their act together can afford. If your sprint board is on fire, your PRs are piling up, and no one knows what’s releasing next week, odds are you’re not updating the wiki. And honestly, you probably shouldn’t be.

But if you do insist on doing documentation—and you should—here’s how to do it right.

🧭 The Documentation Problem

The feedback from engineers at our company was loud and clear:

“Sometimes it's hard to find stuff—would love to see more documentation.”

“The wiki pages feel hard to navigate.”

“It’s difficult to know where to go… README, wiki, Java docs, Swagger? Maybe it just doesn’t exist.”

“Internal documentation is almost always an afterthought, and often ages badly.”

We’ve made improvements. But documentation still feels disorganized, out of date, scattered across systems, and full of assumptions about what the reader already knows. A lot of us end up asking someone directly, copy-pasting from a teammate’s usage, or reverse-engineering how something works instead.

That’s not efficient. That’s expensive.

✅ Recommendations for Documentation That Doesn’t Suck

1. 🛠 Use already well-documented tools and conventions

Don’t create documentation debt you don’t need to. When you use a tool like Storybook, Next.js, or Postgres, you’re buying into a rich ecosystem of documentation and examples. Leverage that.

“I love Storybook, but I feel we could & should be taking full advantage of it.”

Let your tools do some of the heavy lifting. Adopt conventions others understand. Stop over-customizing what already works.

2. 🧾 Write self-commenting code

“In-code documentation is quite rare. We should build a stronger culture around it.”

The best documentation is code that doesn't need any. Descriptive variable names, clean function signatures, and well-structured logic go a long way. If you do leave comments, explain why something exists, not what it does.

No amount of Confluence pages will help if your actual codebase is unreadable.

3. 🔗 Keep documentation close to the code

Docs should live where the code lives—README files, docstrings, Swagger annotations, Storybook stories, etc.

“Is it in the repo? The wiki? Java docs? Swagger? Maybe it just doesn’t exist.”

If someone has to dig through three platforms and a Google Drive folder just to figure out how to use something, they’re not going to use it right. They’re going to guess.

4. 🧹 Document only what matters

“Wiki often goes out of date.”

“Internal documentation… often ages badly.”

Every line of documentation is tech debt waiting to happen. Don’t write a doc just because you feel like you “should.” Write one because it answers a question people actually ask.

Document what’s hard to understand, dangerous to misuse, or essential to onboarding. Let everything else evolve naturally through usage patterns.

5. 🧪 Treat documentation like a product

“We can do a better job keeping documentation up to date and incorporating it within our normal processes.”

“Our documentation efforts are not consistently applied and any mention of it gets left behind the moment we move on.”

Documentation that isn’t maintained becomes a liability. People stop trusting it. It creates confusion, not clarity.

Assign ownership. Set update cadences. Review docs when you review code. If you wouldn’t deploy broken code, don’t leave behind broken documentation.

🔄 Final Thoughts

Good documentation isn’t just about writing things down. It’s about improving developer velocity, onboarding, support, and autonomy. But it’s also work, and it’s only worth doing if you’re going to do it well.

If your team has the bandwidth and maturity to invest in documentation, make it count. Use tools that support you. Keep your docs close to the code. Write only what matters. And maintain it like it’s part of the product—because it is.