Kristian Glass - Do I Smell Burning?

Mostly technical things

Questions Are Documentation Bugs

If I have to ask you a question about how to use your product, your documentation has a bug.

The same holds for many other things. You might have colleagues asking you questions about your project’s progress or goals. Consider that perhaps your transparency has a bug.

When someone asks a question, they’re performing a synchronous high-bandwidth bespoke query. Maybe someone asked you something similar already, so you have a cached response. It still doesn’t scale.

If you’ve already published the information in a useful and discoverable format, then people can query that instead of you. This can be technical documentation, fact sheets, status reports etc., whatever makes most sense. Think of it as a mixture of pub-sub and edge caching.

This is all said with a couple of caveats. As everybody knows, all absolute generalisations are always completely wrong (I really hope you see what I did there). I’m talking about X asking Y a question because Y has knowledge that X desires, and Y will gladly share it. I’m not talking about interrogations, casual conversation, or Who Wants To Be A Millionaire.

The next time someone asks you a question about something, I want you to consider if you could have made that question unnecessary.