Why Great Writing Matters More Than Great Code

There's a myth in software engineering that code speaks for itself. It doesn't. Code speaks to compilers. Humans need words.

The best engineers I've worked with were, without exception, clear writers. Not flowery writers. Not verbose writers. Clear ones. They wrote commit messages that told you why, not just what. They wrote design docs that a new hire could follow. They wrote error messages that helped instead of accused.

This isn't a coincidence.

Writing Is Thinking Made Visible

When you write clearly, you reveal whether you actually understand what you're building. A design doc that's hard to write is a sign that the design is muddled. A commit message that takes five minutes to compose usually means the commit itself is trying to do too much.

Jeff Bezos banned PowerPoint at Amazon and replaced it with six-page memos. The reasoning was simple: writing complete sentences forces complete thinking. Bullet points let you hide behind ambiguity. Full paragraphs don't.

The same principle applies to engineering. A well-written pull request description isn't overhead — it's proof that you understood the problem before you started solving it.

The Documentation Paradox

Everyone agrees documentation matters. Nobody wants to write it. This is because most documentation is written after the fact, as an obligation rather than a tool for thinking.

The fix is to write documentation before you write code. Not formal specs. Just plain English explaining what you're about to build and why. If you can't explain it in a paragraph, you don't understand it yet.

This is why we write detailed API documentation for every Anethoth product before we write the first endpoint. The docs aren't just for users — they're the design document. If an API endpoint is hard to document, the API is wrong.

Error Messages Are UX

Here's a test: open your application's error logs and read the messages as if you were a user encountering them for the first time. Are they helpful? Do they suggest what to do next? Or are they developer shorthand that assumes the reader has your mental context?

Good error messages follow three rules:

1. Say what happened in human language, not HTTP status codes
2. Say why it matters — what the user was trying to do and why it failed
3. Say what to do next — a concrete action, not "please try again later"

"Invalid request" tells you nothing. "Your API key has expired. Generate a new one at /settings/api-keys" tells you everything. The difference is thirty seconds of writing.

Write for the Midnight Reader

Every piece of technical writing has the same audience: someone who is tired, frustrated, and trying to solve a problem at midnight. They don't want to admire your prose. They want to understand your system and get back to bed.

Write for that person. Short sentences. Clear structure. No jargon that doesn't earn its place. Front-load the important information. Use examples liberally — examples are the most efficient form of documentation.

The Career Multiplier

Here's the pragmatic argument: clear writing is a career multiplier. Engineers who write well get promoted because their ideas spread further. An engineer with a great idea and poor communication is indistinguishable from an engineer with no idea at all.

Write the blog post. Write the design doc. Write the commit message that future-you will be grateful for. The code will eventually be rewritten. The clarity you bring to the conversation compounds forever.

Writing isn't a soft skill. It's the hardest skill. And it's the one that separates the engineers who build things from the ones who explain why things should be built — which is ultimately where all the leverage lives.