Arnt Gulbrandsen
About meAbout this blog

FAQ handling

FAQs happen, and have to be handled. There are four ways. A sorted commented list (I promise this won't be a rant):

Do nothing. A valued approach, and there is much to say in its favour. For an opensource hacker who's basically writing code to scratch his own itch (using the male pronoun seems safe in this context) there's no intrinsic reason to care about FAQs at all.

Variants exist. I remember a case where patch to resolve a platform-specific compile error which caused FAQs was rejected because the relevant maintainer hated macs!!!.

Write a list of FAQs which people are supposed to read. This is neat for open source projects, it allows people to enter the project by doing something easy. But it's not actually good.

A good solution would make the problem disappear. This approach allows the problem to form during in the user's use of the program, allows the problem to be put in words, but prevents (mostly) the question from being put to the maintainers. I call that a firewall to shield maintainers from their software's problems.

And, also, dealing with the FAQ lists can be beastly for mortal users — the C++ FAQ/lite must weigh three kilos when printed out.

Answer the FAQ in the documentation for the relevant feature, if any. This is one tick better than the previous, if you ask me, since a user doesn't have to look up the problem in two locations. But it still allows the problem to be formed in the user's work, and navigating the documentation to find the answer may or may not be within reach of a mortal.

A digression perhaps, but when I asked Mikrotik Support what interface wireless set disable-running-check actually does, they not only answered me, but also fixed the documentation for that setting.

Edit the code to make the FAQ go away (or at least become an occasional rather than frequently asked question). This is good. This prevents people from having problems, which is two steps better than merely answering each problem after it's bothered the user.

In the Mikrotik case, this could've been done by making the builtin tab-tab help answer the question at that point in the interface. Usually it takes more work.