15 July, 2007

There is always insufficient information ...

From a long experience on several mailing lists and forums I can tell you there is (nearly) always insufficient information. So thanks go actually to Andrew Stevens for the name of this blog. I laughed sooo much about his post on the Cocoon users list.

But what makes a post actually a good post?

1. Have in mind there are no dumb questions. Even if it has been asked a hundred times. This only means that the answer might be hidden too much in the documentation (a problem the Cocoon documentation suffers from a lot). The users must be taken seriously and so their documentation needs. If the code gets an end in itself the project will get obsolete. So listen to the users.

2. That's actually more a 1b. RTFM. Really, please try to solve an issue you have first on your own. Read the documentation, reference, manual, whatever it is called. Search the mailing lists. Use Google or your search machine of choice. Rarely that issue hasn't occurred before (though somebody must be always the first one obviously). Even if you can not solve the issue on your own having read the documentation will help you to understand (and later explain) the issue better.

3. Give your post a meaningful subject. "Help" is not a good one. Any mentioning of "urgent" is useless, you won't get your answers faster. Don't waste people's time with reading stuff they are actually not interested in.

4. Give context to your issue. Maybe you are trying to achieve something in a completely unusual way - if not even a dead end. Since nobody might have tried it that way and can't help you with your actual issue they might know alternative solutions or workarounds though. It makes it also easier to try to understand your issue.

X. Use an appropriate way of writing and styling your post. You should only post in plain text to mailing lists. That's not because all developers are purists, it's a matter of readability in the mailing list archives. Reading a HTML-mail in the archive is like reading the HTML-source of a web-page - or even worse since < and > are often escaped to &lt; and &gt;.
In forums it's the other way around. Reading code in variable-width fonts is really hard, not to forget that the code loses its indentation since the whitespaces get collapsed in HTML.

XX. To be completed ...

3 comments:

Karl Moore said...

I also think references like this would be useful for the forum.
http://www.hibernate.org/160.html

joerg20 said...

Thanks for the link, Karl. It's a good list for the issues in general. But I absolutely dislike the tone of this document. It is as arrogant as I always experienced the Hibernate community. There is a minor difference between Don't blame Hibernate. 99% of posts titled "bug in Hibernate" are simple user error. and my items 1 and 2.

Karl Moore said...

I do agree with you about the tone. It seems to be a general theme with Hibernate. Apart from that I agree with most of it. It's so frustrating when your first response to a post has to be, please post the stacktrace and also some code and configuration :-).