: New: FAQs, Facts, Drowning in Questions

You're a small team of software developers. You make a service|API|tool|thingy used by many, many software developers. They have questions, so many questions. You're drowning in questions. How can you make the questions stop? Maybe you can stop the questions with documentation. Build a thick wall of documentation around your team. Or maybe that's a terrible idea.

You want to stop the boring questions. You want to preserve a trickle of interesting questions.

I tend to work with teams who are drowning in questions, trying to shield themselves behind a big pile documentation. (I'm a technical writer; it turns out that writing a big pile of documentation is a lot of work. Some teams ask for help.) When I was young and naive, I set out with the goal to document everything. I thought that nobody should ever have to ask for help (except for those folks too lazy to study). But now? Now I prefer to leave some gaps, leave some room for conversation. Some folks will ask you questions; it's good that they do; you want to hear them.

When a question is asked and answered, there's more learned than just the answer to that question.

Not all questions lead to such inspiration, of course. The fifth time you answer that same dull question, you're sick of that question. You can feel like you're drowning.

The book The Social Life of Information explores how knowledge oozes through an engineering organization. (Spoiler: Documentation helps, but conversations help more.) Knowledge Sharing in Software Development reminds us that pair programmers share knowledge without even trying; contrariwise, developers don't always choose useful things to document; it's easy to waste time answering questions that nobody will ask.

What can you do? If documentation is so useless, why am I still a professional technical writer? Well, it's not useless. It's useful, you just don't want to go overboard.

Answer the boring questions with documentation.

If someone asks you that same old question, you should have documentation that answers it. If you're tired of answering that question, then don't; point folks at the already-existing answer instead.

Ask them for help in writing the documentation.

Let through a trickle of interesting questions.

You want to let through just enough questions to make sure you're in touch with your customers. Depending on how many of those people there are, you want a loose filter or a strict one. If you're a team of six supporting 60 developers, you probably can sit by them without getting too many questions. If your team of six supports 600 developers, you want to make sure they check a FAQ first. If you support 6000 developers, you probably erect more barriers: rules about how to submit questions. If you support 60000 developers, only those who are pure of heart and can find you at the top of the mountain can ask.

If you get the balance right, you might be genuinely glad when a question gets through to you. Your delight might even keep your customers thinking that you care about them.

Tags: writing instructional design programming

blog comments powered by Disqus