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

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).

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

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).