PerryLorier originally wrote this as a mailing list post.

As a programmer, things I love non-programmers to do:

Write good bug reports

A bug report means absolutely nothing if I can't reproduce the bug. If I can't reproduce it it means I can't prove that I've fixed it. A bug report I got in the past:

Subject: [SEVERE BUG] Crash after 10 minutes

The server crashes after 10 minutes, the server isn't in the process list anymore.

I mean, what am I supposed to do with this? After 10 minutes it's still working for me...

Things to include:

• What OperatingSystem you are running (the output of uname -a), what version of the software you are running. What LinuxDistribution you are running (and which version of that distro).
• The config file you are using (remember to remove passwords!)
• Tell me what was happening at the time (netsplit?)
• If it produces any error messages, please please please tell me what they are! "assertion failure 0 != cptr at client.c:212" may not mean much to you, but it means the world to me.
• Run it with full DeBugging on, and either send the full debug log, or if it's huge, just the last 1mb or so.

• If it generates a core file, I will want a backtrace. This is easy to get with gdb(1):

  $ gdb ./program-that-crashed ./core
  (gdb) bt full

  and paste the entire output into the bug report. Please don't just send me the core file, in general it's useless to me, and I don't want a 1gig file emailed to me that I can't use.

Also, I'm a programmer, I suck at documentation. It's far too easy to think "that's obvious", or just use bad terminology or spelling. What really helps is getting someone who isn't a programmer to give the documentation a once over and send in suggestions. The WlugWiki is a great example of this. If someone asks me something I usually try and get them to wiki it. Why? Because if I have to wiki everything I'm asked, I'm gonna give up answering questions, and people tend to wiki things from their point of view ("I want to do this") as opposed to mine ("this is how the program works"). I always go back and check what people wrote to check it for accuracy and for clarifications.

If you have a problem and spend time researching it and find the answer, please wiki it, so that others can benefit from your help, or more importantly in 6 months when you're trying to remember how you did whatever you did you have a reference. Writing up HowTo documents in the wiki is surprisingly addictive, as is cleaning up old pages in the wiki. Perhaps you might like to start at WantedWikis...

CategoryBeginners, CategoryProgrammingBugs