Archives

After 25 years in IT, I still see the same problem everywhere: products that deserve better documentation than they have.

When two products are roughly equal, documentation often decides which one wins.

AI can help with documentation. It can't replace the person who understands the product and the user.

Every product that has users has a documentation problem. Software just makes it more visible.

You don't need perfect documentation. You need enough documentation that users can succeed.

Open source documentation ranges from exceptional to nonexistent. The difference is almost never about talent.

UX writing and technical writing serve different moments in a user's journey. Understanding the difference makes both better.

A changelog is not a formality. It's documentation for the people who already use your product.

PDF documentation feels professional. It's also often the worst format for the people who need the information.

Treating documentation like code — with Git, pull requests, and CI/CD — changes how teams relate to it.

The README is the front door of your project. Most of them are locked.

Both roles care about documentation. They approach it from different directions.

Mark Baker's concept changed how I think about structuring documentation. Nobody starts at the beginning anymore.

API documentation has its own rules. Here's what separates the docs developers actually use from the ones they ignore.

Write the Docs is a conference and a community. After speaking there, here's what stayed with me.

Documentation is not the thing you do after shipping. It's part of what you ship.

It's not laziness. The reasons developers avoid documentation are structural, cultural, and sometimes entirely reasonable.

Daniele Procida's Diataxis framework gives documentation a clear map. Here's what the four types are and why the distinction matters.

Bad documentation has a price. It shows up in support tickets, lost users, and products that never reach their potential.

Every few years someone declares documentation dead. AI is the latest reason. They're wrong, and here's why.