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.
- The expert finds out what other folks' interests. Maybe a feature request hides in that question. "Does it reticulate splines?" "No, but maybe it should" Maybe that question is actually a bug report in disguise. "Is this supposed to be on fire?"
- The expert gets to demonstrate kindness. Later on, when folks want a new feature they might ask for it nicely instead of muttering "I'd rather work a year making our own than ask that jerk to add this feature."
- The questioner might realize they're part of a helpful community. When they hear questions on this topic, they might pipe up with answers.
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.
Give them an answer, but for a price: it's up to them to paste that answer into the wiki.
Ask them what they searched for when they tried to find the answer on their own. You might find out that potential customers fail to find answers because they use the wrong words. Add those "wrong word" questions to your FAQ, with answers that let them know how they should think about their question.
- Take the Stack Overflow approach: the way to ask a question is to add it to the FAQ (and hope someone comes along to answer it).
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.
Shady Characters has nudged the course of my life in recent years.
A few years back, some folks put together some resources to help folks learn the arcana of puzzlehunts. (Yes, there are mysteries, customs. Thinking about answer-extraction yields insights that let you skip parts. You are expected to recognize the six-dot Braille alphabet; you are not expected to know Braille contractions, eight-dot Braille symbols… That kind of thing.) Scott Royer had written an awesome puzzlehunt guide with a walkthrough for one puzzle. I was working at Google's engEDU team, hearing about Instructional Design and Theories of Learning all day. There are plenty of those Theories running around, but most agree: if you want someone to remember what you just taught them, give them a way to apply what they learned right away. So we wanted some more sample puzzles as exercises: nothing super-amazing, but something straightforward for Morse code, something for anagramming, something for indexing… Writing a puzzle with the only constraint "It should use Morse code" ain't so easy—you can do anything. If we had a theme, that would jump-start plenty of puzzles. But what theme?
I'd been reading the Shady Characters blog, reading about the history of punctuation. Most of these stories are of the form: over history, several symbols indicated the same thing. Before there were modern quotation marks, there were: different marks out in the margin, indented text with marks at the left edge; marks at the left edge with a different mark embedded in the text; different marks embedded in the text. But #'s story in the blog was different: # had been around roughly forever, but it meant different things over time and was called by different names.
So I used # as the theme for some sample exercise puzzles. Because # meant different things, there was still some variety. Several months later, there were quite a few puzzles. As the blog continued, more puzzle ideas resulted. Someone familiar with Swedish pointed out that # was a map symbol for a lumberyard. As you would expect, that inspired some lumber-ish puzzles.
Anyhow, when the book came out, I picked it up. It's a fun read; it's probably smoother to read the book than to pick your way through the blog. Usually, I'm a Kindle kind of guy, but I'm glad I got this book on paper. So far, most of the history of punctuation is tied up with the history of printing: scribes' marginalia, early typesetting. The physical book illustrates a lot of the type-ish things by using them itself; I suspect that wouldn't work so well on a Kindle. I read it over, got yet more puzzle ideas. But you might like the book even if you're not using it to get puzzle ideas.
Them: "This is terrible. This is way too complicated"
Roz: "Is it wrong?"
The book Confluence, Tech Comm, Chocolate is for, by, and about technical writers. It's about keeping documentation in a wiki. I didn't learn so much from that part; I've been keeping docs in wikis for several years now. But it was specifically about Confluence wiki, and I'd heard that it had a section on how Confluence's search computes relevance ranking. We use Confluence at work, so there were some things I wanted to know about; how to do "intranet SEO" was a big one. From that I learned… Confluence's search doesn't work the way I want it to. Findability isn't a big problem for us now; but it probably will be sometime in the next couple of years. And we might not have great tools to fix it then.
This is terrible.
By which I mean, "Thank you for the early warning."