How to be helpful

Along the lines of the many, many "netiquette" sermons out there, here is a sermon on how to give good help on a technical mailing list.

If you want to provide an answer to someone:

  1. Make sure your information is APPLICABLE. This boils down to being sure you understand the question. If you don't understand the question, or even worse if you misunderstand it, your advice will be useless at best and damaging at worst. If necessary, ask questions to clarify the problem.
  2. Make sure your information is CORRECT. There is a very big difference between confidence and knowledge. Don't be "reasonably sure" or "fairly confident" or any other hazy equivalent: KNOW. Basically this means that you have had either the same problem or a very similar one yourself, and have found a solution.
  3. Make sure your information is EXACT. If you recommend specific actions (a command, a script, a click sequence etc.) then make sure you have actually carried out precisely those actions yourself. If you have not done this, then SAY SO and make it clear to all that they must triple check everything themselves. Be especially clear about this if the actions are dangerous.
  4. Make sure your information is COMPLETE. Terse is OK. Obtuse is not. If someone asks how to flibble a wodget, don't just answer "run /usr/sbin/flibbler". Direct them to a man page, or to a good description on the Web, or give a short description of the appropriate command and parameters, or whatever. Definitely warn them about any dire side effects, or things they may need to do before or after the wodget has been flibbled.
  5. Make sure your information is QUALIFIED. An answer that makes sense in one context might be very dangerous in another context. For example, advising someone to run a particular program as root may be a valid solution to their particular problem. Advising them to run *all* programs as root to solve their problem would be very bad advice. Also, not everybody is running the same hardware or the same versions of the operating system. If your advice has limited applicability, state those limits clearly.
  6. Make sure information is CLEAR. Don't obscure what you are saying with jargon, acronyms, abbreviations, weird punctuation or bad spelling. Keep it simple and straight.
  7. Don't be sarcastic, don't be rude, don't make jokes. Not everyone will be able to distinguish sarcastic advice or joke advice from real advice, and rudeness just obscures your message. Telling a newbie to "rm -fr /" is not original, not helpful and NOT FUNNY. And it's not just newbies; many people do not speak or read English very well.
  8. Separate FACT from OPINION. If you wish to state an opinion, make sure it is CLEAR that your statement is opinion. Opinion - other than about a technical issue, of course - is very rarely appropriate on any technical list.
  9. CHECK your answer. Read it through, carefully. Go through the above checklist in your head. Then ask yourself "If it was my problem, and I got this response, would I be pleased?" If the answer is anything but "yes", don't send your message. There'll be a next time...

[Email me!] [Home]
Page last updated 12 June 2008