Heidi Waterhouse

139 points
A pink-haired woman with a half-smile looks directly into the camera.
Minneapolis, MN

Heidi is a technical writer, speaker, and developer coach who is working on scaling her writing and industry expertise to help more people be better writers. Her current passions include automated documentation, docs-driven development, and sewing pockets into all her clothes.

Open Minded Author

Authored Content

Authored Comments

A pink-haired woman with a half-smile looks directly into the camera.
HWaterhouse
How do we fix the state of technical documentation?

I agree with you to a degree, but I think part of the problem may be that we are failing to motivate anyone properly. I'm going to go noodle on this in a personal blog post in a couple days.

A pink-haired woman with a half-smile looks directly into the camera.
HWaterhouse
4 steps to better documentation: How to get users the exact answer to the problem

It's certainly true that new users are sometimes unclear on how to frame their questions, Greg, but I think it's also a good time for us to slow down and make sure that we are not pre-supposing a bunch of jargon before they ca even get to ask the question.

It probably depends on the writers, the users, and the tech stack, when it comes down to it. I know that when I started using FrameMaker, I didn't even have the specialist vocabulary to ask intelligbile questions, and it took a lot of patience from the community to bring every new user up to speed.

I'd like our documentation to feel less like patience, and more like transparency. Always an ideal!