Twitter github

Open Source Bug Reporting Etiquette

Over the weekend, I noticed a bug trickle in…

I first thought… wow what a !@#$, this is not a way to win friends and influence people

I was thankful my team responded correctly with the mantra of killing people with kindness.

As open source developers, we have to remember to have some restraint when interacting with our consumers. The old adage of killing people with kindness should apply to most of the cases we deal with. As consumers of open source software, it’s important to follow some basic etiquette rules when hitting a problem and reporting a bug:

  • Be civil and positive when reporting bugs. Saying the !@#$ing software sucks isn’t going to help.
  • Be patient when reporting bugs. Some people work on projects on a volunteer basis (if you need better support, some open source projects have commercial support offerings).
  • Don’t double post and spam all the open source project’s communication channels.
  • Read “How to Ask Questions the Smart Way” and live by it

In the end, it’s all about interacting with people. Over the net, it’s easy to forget that we are actually dealing with people; not autonomous robots without any emotion.

  • Perhaps we should redirect all bugzillas that contains words like “sucks” or “crap” to an ever so polite and talkative robot. Like an intelligent spam-filter that would keep the reporter busy for a while until he figures out who's on the other side of the dialog 🙂

  • ragerino

    this bugzilla entry is comprehensible for me.

    i'm developing rcp-apps for a huge pharmaceutical company. we decided two years ago to swith from swing to eclipse-rcp. the switch was really hard, because eclipse lacks massively on the documentation side because …

    … most of the documentation is outdated (written for older eclipse versions).
    … lots of the projects don't even have documentation.
    … most of the examples don't work, because of api changes.
    … documentation is not cross referenced.
    … documentation is not homogen (project site, wiki, pdf, mailing lists, non existent).
    … screenshots in your documentation reffer to options that don't exist.

    most of the time screenshots differ more than 50% to the current eclipse version. for me it's not really a problem because i know ecllipse since its first version. but for someone who just started using eclipse, it must be really frustrating. no wonder that visual studio (imho eclipse is much better) still has such a big user-base.

    posting the link “How to ask Questions the Smart Way” isn't really constructive and sounds arrogant to me. you guys at eclipse foundation should do your homework first and make it easier for non-core-eclipse develpers to find the information they're looking for.

    documentation should be an essential part of every eclipse project.

    every document should, have some core info's like:
    – applies to ecllpse version <from>-<to>
    – some possibility to rate a document (0-5 star rating)
    – reference to other eclpse documents (e.g. “use target platform 3.4” -> link to document describing how to set up a target platform)

    every code-example should have:
    – informations about the requirements (working with eclispe <version number>, plugins, jars, …)
    – link to a public repository to check out the whole example workspace (i liked the e4 example projects, where i just had to check out and import a project-set)

    if something doesn't work any more or documentation is outdated it should be easy to create a bugzilla request so the author or some proxy will be informed.

    i'd propose that eclilpse documentation should be an essential part of every eclipse-project, and should be revisioned with every new version of the project.

    i would be much more productive if i wouldn't need to read eclipse source code all the time, trying to find out how you guys solved some things.

    and finally something positive: the eclipse forums are a huge imporvement, despite of the fact that forums are a replacement for mailing lists for a long time for the rest of the internet. maybe eclipse will have useable documentation in 10 years (hint: cms = content management system).

  • ragerino

    perhaps you should spend more time on documentation. try to imagine, that this guy isn't into ecllipse business since more than 10 years.

  • “posting the link “How to ask Questions the Smart Way” isn't really constructive and sounds arrogant to me. you guys at eclipse foundation should do your homework first and make it easier for non-core-eclipse develpers to find the information they're looking for.”

    First off, it isn't arrogant of us to ask people to ask questions the smart way instead of dealing with offensive language on bug reports. Not asking the questions the right way isn't constructive.

    Second, the Eclipse Foundation doesn't have any developers. The staff at the foundation simply assists in making sure the Eclipse infrastructure is running (website, wiki, legal services, etc…). Each project at Eclipse.org is run individually by the respective project leadership. Each project could have different levels of documentation depending how the project is ran.

    Third, you should know that working with open source isn't always “free” by now. The documentation may not always be up to date along with other things. Eclipse has an ecosystem of commercial service providers that can assist you with developing applications if you really need the help.

    I understand your frustration, as I've experienced it with other open source projects (Lucene in particular). I think it's part of the cost of using open source. If we find issues like documentation problems, we do our best to contribute back to move forward the state of the software. That's the only way things will improve instead of complaining about them 🙂

  • ragerino

    this bugzilla entry is comprehensible for me.

    i'm developing rcp-apps for a huge pharmaceutical company. we decided two years ago to swith from swing to eclipse-rcp. the switch was really hard, because eclipse lacks massively on the documentation side because …

    … most of the documentation is outdated (written for older eclipse versions).
    … lots of the projects don't even have documentation.
    … most of the examples don't work, because of api changes.
    … documentation is not cross referenced.
    … documentation is not homogen (project site, wiki, pdf, mailing lists, non existent).
    … screenshots in your documentation reffer to options that don't exist.

    most of the time screenshots differ more than 50% to the current eclipse version. for me it's not really a problem because i know ecllipse since its first version. but for someone who just started using eclipse, it must be really frustrating. no wonder that visual studio (imho eclipse is much better) still has such a big user-base.

    posting the link “How to ask Questions the Smart Way” isn't really constructive and sounds arrogant to me. you guys at eclipse foundation should do your homework first and make it easier for non-core-eclipse develpers to find the information they're looking for.

    documentation should be an essential part of every eclipse project.

    every document should, have some core info's like:
    – applies to ecllpse version <from>-<to>
    – some possibility to rate a document (0-5 star rating)
    – reference to other eclpse documents (e.g. “use target platform 3.4” -> link to document describing how to set up a target platform)

    every code-example should have:
    – informations about the requirements (working with eclispe <version number>, plugins, jars, …)
    – link to a public repository to check out the whole example workspace (i liked the e4 example projects, where i just had to check out and import a project-set)

    if something doesn't work any more or documentation is outdated it should be easy to create a bugzilla request so the author or some proxy will be informed.

    i'd propose that eclilpse documentation should be an essential part of every eclipse-project, and should be revisioned with every new version of the project.

    i would be much more productive if i wouldn't need to read eclipse source code all the time, trying to find out how you guys solved some things.

    and finally something positive: the eclipse forums are a huge imporvement, despite of the fact that forums are a replacement for mailing lists for a long time for the rest of the internet. maybe eclipse will have useable documentation in 10 years (hint: cms = content management system).

  • ragerino

    perhaps you should spend more time on documentation. try to imagine, that this guy isn't into ecllipse business since more than 10 years.

  • “posting the link “How to ask Questions the Smart Way” isn't really constructive and sounds arrogant to me. you guys at eclipse foundation should do your homework first and make it easier for non-core-eclipse develpers to find the information they're looking for.”

    First off, it isn't arrogant of us to ask people to ask questions the smart way instead of dealing with offensive language on bug reports. Not asking the questions the right way isn't constructive.

    Second, the Eclipse Foundation doesn't have any developers. The staff at the foundation simply assists in making sure the Eclipse infrastructure is running (website, wiki, legal services, etc…). Each project at Eclipse.org is run individually by the respective project leadership. Each project could have different levels of documentation depending how the project is ran.

    Third, you should know that working with open source isn't always “free” by now. The documentation may not always be up to date along with other things. Eclipse has an ecosystem of commercial service providers that can assist you with developing applications if you really need the help.

    I understand your frustration, as I've experienced it with other open source projects (Lucene in particular). I think it's part of the cost of using open source. If we find issues like documentation problems, we do our best to contribute back to move forward the state of the software. That's the only way things will improve instead of complaining about them 🙂