Home » General (non-technical) » Eclipse Foundation » Documentation structure on eclipse.org and associated web sites
| Documentation structure on eclipse.org and associated web sites [message #47627] |
Thu, 02 August 2007 23:55  |
 Volker Renneberg
Messages: 8
Registered: July 2009 |
Junior Member |
|
|
Hi!
Some days ago I found the phoenix project which seemed to develop a new
content management system for the Eclipse web page. However, there is no
newsgroup activity anymore and the following question has not been answered.
I was working with Eclipse as a Java development platform for quite a while
and started to look at the RCP features one or two weeks ago. Due to the
complexity of the whole issue I tried to find information on RCP, different
ongoing projects+description, available plugins, API/Javadoc.
Looking at the phoenix project, it all looks very technical. With my
experience during the last two weeks I am very interested whether there is a
more conceptual view on the available and required information on the
Eclipse website. While trying to grasp all the details necessary to develop
plugins, I got lost very very fast.... I believe, all the necessary
documentation is available on the Eclipse site and associated sites. But I
somehow miss a common structure (for all projects). For example I looked for
some starting points for plugin development and I think I finally found some
of them. But the problem is: You only find those starting points if you know
what to look for.
I would so much be interested in a non-programmatic structural view on the
final website structure. Are there any plans to delve into those knowledge
management issues? To be more precise: I am not interested in how to
develop a site. I am interested in knowledge management aspects. How will
the site develop in the next months.
If no work is being done in this direction, I would not mind to write some
documentation with feedback and - to my mind - necessary structural changes.
Cheers
Volker
--
Volker Renneberg, Dipl.-Inform. (univ.)
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47660 is a reply to message #47627] |
Fri, 03 August 2007 11:21  |
Eclipse User |
|
|
|
Originally posted by: alex_blewitt.yahoo.com
I think pheonix was just a revamp of the way that the site looked, rather than anything grander. I don't think you'll find anything on there that will be of any use in your quest.
Have a look at the 'getting started with eclipse plugins' series we've been running on EclipseZone, or the articles/tutorials on RCP development at www.eclipse.org/articles
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47689 is a reply to message #47660] |
Fri, 03 August 2007 14:22 |
Volker Renneberg
Messages: 8
Registered: July 2009 |
Junior Member |
|
|
Hi!
Thanks for the link. However, I am still interested in the actual issue of
my last posting. There is a lot of information around Eclipse available in
all different types of media formats (books, articles, etc). Since user
adoption of Eclipse as a development platform, application framework,
enterprise framework, etc. really depends on the documentation, I think
Eclipse.org can do much better. Currently, all the information is somehow
semi-structured based on the datatypes of information that is available. The
first of the website divides into five sub-categories with the relevant
projects.
But below the top level structure of the first page, the strategy of the
web-page seems to be "give the user all the information that is available"
rather than "give the information the user needs to accomplish a specific
task".
I am interested, whether there is an information management strategy defined
for the web-pages. And whether there has been user research on how the
web-page fulfills its needs.
In my mind a more integrative and user and task oriented information
presentation is necessary on the webpage. But maybe I am alone with this
view.... I would like to invest some work on this if appreciated.
So, what does the community think?!
Cheers
Volker
"Alex Blewitt" <alex_blewitt@yahoo.com> wrote
news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com...
>I think pheonix was just a revamp of the way that the site looked, rather
>than anything grander. I don't think you'll find anything on there that
>will be of any use in your quest.
>
> Have a look at the 'getting started with eclipse plugins' series we've
> been running on EclipseZone, or the articles/tutorials on RCP development
> at www.eclipse.org/articles
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47718 is a reply to message #47689] |
Fri, 03 August 2007 14:44 |
| Eclipse User |
|
|
|
Originally posted by: merks.ca.ibm.com
This is a multi-part message in MIME format.
--------------010600080902090901030202
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Volker,
I think a fundamental problem is that developers really like to develop
and when they are also the same folks who must not only write all the
documentation, but also maintain it and organize it effectively as well,
time trade-offs need to be made. Guess what developer chose as their
priority? This is of course short sighted since if clients can't
figure out how to use it why bother developing it? Of course as
developers we realize this, but constraints are what they are. The
foundation itself is similarly resource constrained, so even with the
best of intentions, it's just not possible to achieve a state even close
to optimal. I know folks often complain about EMF's lack of
documentation for example, but my sympathy in this regard is somewhat
limited (and I quietly take satisfaction from this being the biggest
complaint rather than bugs or other quality issues). Certainly there is
ample opportunity for the community to contribute in this regard, but
that suggestion usually silences the critics quite effectively, which of
course misses the point entirely...
So while I'm sure a lot of people would share your view, including me,
it's not so clear how to make changes happen with limited budgets and
constrained resources...
Volker Renneberg wrote:
> Hi!
>
> Thanks for the link. However, I am still interested in the actual issue of
> my last posting. There is a lot of information around Eclipse available in
> all different types of media formats (books, articles, etc). Since user
> adoption of Eclipse as a development platform, application framework,
> enterprise framework, etc. really depends on the documentation, I think
> Eclipse.org can do much better. Currently, all the information is somehow
> semi-structured based on the datatypes of information that is available. The
> first of the website divides into five sub-categories with the relevant
> projects.
>
> But below the top level structure of the first page, the strategy of the
> web-page seems to be "give the user all the information that is available"
> rather than "give the information the user needs to accomplish a specific
> task".
>
> I am interested, whether there is an information management strategy defined
> for the web-pages. And whether there has been user research on how the
> web-page fulfills its needs.
>
> In my mind a more integrative and user and task oriented information
> presentation is necessary on the webpage. But maybe I am alone with this
> view.... I would like to invest some work on this if appreciated.
>
> So, what does the community think?!
>
> Cheers
> Volker
>
> "Alex Blewitt" <alex_blewitt@yahoo.com> wrote
> news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com...
>
>> I think pheonix was just a revamp of the way that the site looked, rather
>> than anything grander. I don't think you'll find anything on there that
>> will be of any use in your quest.
>>
>> Have a look at the 'getting started with eclipse plugins' series we've
>> been running on EclipseZone, or the articles/tutorials on RCP development
>> at www.eclipse.org/articles
>>
>
>
>
--------------010600080902090901030202
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
Volker,<br>
<br>
I think a fundamental problem is that developers really like to develop
and when they are also the same folks who must not only write all the
documentation, but also maintain it and organize it effectively as
well, time trade-offs need to be made. Guess what developer chose as
their priority? This is of course short sighted since if clients
can't figure out how to use it why bother developing it? Of course as
developers we realize this, but constraints are what they are. The
foundation itself is similarly resource constrained, so even with the
best of intentions, it's just not possible to achieve a state even
close to optimal. I know folks often complain about EMF's lack of
documentation for example, but my sympathy in this regard is somewhat
limited (and I quietly take satisfaction from this being the biggest
complaint rather than bugs or other quality issues). Certainly there
is ample opportunity for the community to contribute in this regard,
but that suggestion usually silences the critics quite effectively,
which of course misses the point entirely...<br>
<br>
So while I'm sure a lot of people would share your view, including me,
it's not so clear how to make changes happen with limited budgets
and constrained resources...<br>
<br>
<br>
Volker Renneberg wrote:
<blockquote cite="mid:f8vdlj$8pc$1@build.eclipse.org" type="cite">
<pre wrap="">Hi!
Thanks for the link. However, I am still interested in the actual issue of
my last posting. There is a lot of information around Eclipse available in
all different types of media formats (books, articles, etc). Since user
adoption of Eclipse as a development platform, application framework,
enterprise framework, etc. really depends on the documentation, I think
Eclipse.org can do much better. Currently, all the information is somehow
semi-structured based on the datatypes of information that is available. The
first of the website divides into five sub-categories with the relevant
projects.
But below the top level structure of the first page, the strategy of the
web-page seems to be "give the user all the information that is available"
rather than "give the information the user needs to accomplish a specific
task".
I am interested, whether there is an information management strategy defined
for the web-pages. And whether there has been user research on how the
web-page fulfills its needs.
In my mind a more integrative and user and task oriented information
presentation is necessary on the webpage. But maybe I am alone with this
view.... I would like to invest some work on this if appreciated.
So, what does the community think?!
Cheers
Volker
"Alex Blewitt" <a class="moz-txt-link-rfc2396E" href="mailto:alex_blewitt@yahoo.com"><alex_blewitt@yahoo.com></a> wrote
<a class="moz-txt-link-freetext" href="news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com">news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com</a>...
</pre>
<blockquote type="cite">
<pre wrap="">I think pheonix was just a revamp of the way that the site looked, rather
than anything grander. I don't think you'll find anything on there that
will be of any use in your quest.
Have a look at the 'getting started with eclipse plugins' series we've
been running on EclipseZone, or the articles/tutorials on RCP development
at <a class="moz-txt-link-abbreviated" href="http://www.eclipse.org/articles">www.eclipse.org/articles</a>
</pre>
</blockquote>
<pre wrap=""><!---->
</pre>
</blockquote>
<br>
</body>
</html>
--------------010600080902090901030202--
|
|
| |
| Re: Documentation structure on eclipse.org and associated web sites [message #47777 is a reply to message #47748] |
Fri, 03 August 2007 16:01 |
| Eclipse User |
|
|
|
Originally posted by: merks.ca.ibm.com
Stéphane,
Yes, I was hoping that would be the case too. I'm sure many people
would be pleased to see such an effort and would provide moral support
and perhaps even a little more than that. It's way too hard to find the
things you need at Eclipse and often way too easy to do things wrong.
For example, installing the Java EE package can be accomplished so
easily with just two clicks. But when it doesn't work, people get
frustrated. Often their install picks up a 1.4 JRE and there isn't a
single user level message that tells them "Hey, we know you wanted Java
EE support, but all those plugins are disabled because you must have a
5.0 JRE". The main download web page says a Java 5 JRE is recommended
when in fact for the EE package its absolutely required. And while I'm
busy being the critic, how many people need to be told to use -clean
when they unzip something new; it's not like this is obvious, so I have
to wonder if checking if the timestamp of the plugins folder has
changed is really so expensive (but maybe there's a good reason this is
a bad idea). And of course there's the ever recurring, I updated my
classpath to fix compile errors but now my plugin doesn't run; changing
the classpath manually for a plugin is almost a sure formula for runtime
problems. I'm starting to feel like a harpie! I'd better stop...
Stéphane LACRAMPE wrote:
> Ed,
>
> I agree with you in the sense that in the end, it is easier (not easy)
> to find developers who wants to contribute to an open source project
> that resources who wants to spend time on documentation, or on
> infrastructure, build and administration for example.
> But what I understand from Volker last sentence is that he would be
> willing to start some work on thinking how to organize in a better way
> the documentation that is provided.
> So maybe the question he is asking is : is there any appropriate place
> in Eclipse to start this thinking on how to better organize Eclipse
> project documentation ?
>
> Stephane
>
>
> Ed Merks a écrit :
>> Volker,
>>
>> I think a fundamental problem is that developers really like to
>> develop and when they are also the same folks who must not only write
>> all the documentation, but also maintain it and organize it
>> effectively as well, time trade-offs need to be made. Guess what
>> developer chose as their priority? This is of course short sighted
>> since if clients can't figure out how to use it why bother developing
>> it? Of course as developers we realize this, but constraints are
>> what they are. The foundation itself is similarly resource
>> constrained, so even with the best of intentions, it's just not
>> possible to achieve a state even close to optimal. I know folks
>> often complain about EMF's lack of documentation for example, but my
>> sympathy in this regard is somewhat limited (and I quietly take
>> satisfaction from this being the biggest complaint rather than bugs
>> or other quality issues). Certainly there is ample opportunity for
>> the community to contribute in this regard, but that suggestion
>> usually silences the critics quite effectively, which of course
>> misses the point entirely...
>>
>> So while I'm sure a lot of people would share your view, including
>> me, it's not so clear how to make changes happen with limited budgets
>> and constrained resources...
>>
>>
>> Volker Renneberg wrote:
>>> Hi!
>>>
>>> Thanks for the link. However, I am still interested in the actual
>>> issue of my last posting. There is a lot of information around
>>> Eclipse available in all different types of media formats (books,
>>> articles, etc). Since user adoption of Eclipse as a development
>>> platform, application framework, enterprise framework, etc. really
>>> depends on the documentation, I think Eclipse.org can do much
>>> better. Currently, all the information is somehow semi-structured
>>> based on the datatypes of information that is available. The first
>>> of the website divides into five sub-categories with the relevant
>>> projects.
>>>
>>> But below the top level structure of the first page, the strategy of
>>> the web-page seems to be "give the user all the information that is
>>> available" rather than "give the information the user needs to
>>> accomplish a specific task".
>>>
>>> I am interested, whether there is an information management strategy
>>> defined for the web-pages. And whether there has been user research
>>> on how the web-page fulfills its needs.
>>>
>>> In my mind a more integrative and user and task oriented information
>>> presentation is necessary on the webpage. But maybe I am alone with
>>> this view.... I would like to invest some work on this if appreciated.
>>>
>>> So, what does the community think?!
>>>
>>> Cheers
>>> Volker
>>>
>>> "Alex Blewitt" <alex_blewitt@yahoo.com> wrote
>>> news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com...
>>>
>>>> I think pheonix was just a revamp of the way that the site looked,
>>>> rather than anything grander. I don't think you'll find anything on
>>>> there that will be of any use in your quest.
>>>>
>>>> Have a look at the 'getting started with eclipse plugins' series
>>>> we've been running on EclipseZone, or the articles/tutorials on RCP
>>>> development at www.eclipse.org/articles
>>>
>>>
>>>
>>
>
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47807 is a reply to message #47777] |
Fri, 03 August 2007 17:07 |
| Eclipse User |
|
|
|
Originally posted by: atoulme.intalio.com
+1, The website is hard to harvest. Rethink the way the content is
accessed would be great.
Volker, if you are able to nail down specific issues, please open bugs
regarding them, and give their numbers here. I will be happy to help (in
the limits of the time I can afford on this).
Antoine
Ed Merks wrote:
> Stéphane,
>
> Yes, I was hoping that would be the case too. I'm sure many people
> would be pleased to see such an effort and would provide moral support
> and perhaps even a little more than that. It's way too hard to find the
> things you need at Eclipse and often way too easy to do things wrong.
> For example, installing the Java EE package can be accomplished so
> easily with just two clicks. But when it doesn't work, people get
> frustrated. Often their install picks up a 1.4 JRE and there isn't a
> single user level message that tells them "Hey, we know you wanted Java
> EE support, but all those plugins are disabled because you must have a
> 5.0 JRE". The main download web page says a Java 5 JRE is recommended
> when in fact for the EE package its absolutely required. And while I'm
> busy being the critic, how many people need to be told to use -clean
> when they unzip something new; it's not like this is obvious, so I have
> to wonder if checking if the timestamp of the plugins folder has
> changed is really so expensive (but maybe there's a good reason this is
> a bad idea). And of course there's the ever recurring, I updated my
> classpath to fix compile errors but now my plugin doesn't run; changing
> the classpath manually for a plugin is almost a sure formula for runtime
> problems. I'm starting to feel like a harpie! I'd better stop...
>
>
> Stéphane LACRAMPE wrote:
>> Ed,
>>
>> I agree with you in the sense that in the end, it is easier (not easy)
>> to find developers who wants to contribute to an open source project
>> that resources who wants to spend time on documentation, or on
>> infrastructure, build and administration for example.
>> But what I understand from Volker last sentence is that he would be
>> willing to start some work on thinking how to organize in a better way
>> the documentation that is provided.
>> So maybe the question he is asking is : is there any appropriate place
>> in Eclipse to start this thinking on how to better organize Eclipse
>> project documentation ?
>>
>> Stephane
>>
>>
>> Ed Merks a écrit :
>>> Volker,
>>>
>>> I think a fundamental problem is that developers really like to
>>> develop and when they are also the same folks who must not only write
>>> all the documentation, but also maintain it and organize it
>>> effectively as well, time trade-offs need to be made. Guess what
>>> developer chose as their priority? This is of course short sighted
>>> since if clients can't figure out how to use it why bother developing
>>> it? Of course as developers we realize this, but constraints are
>>> what they are. The foundation itself is similarly resource
>>> constrained, so even with the best of intentions, it's just not
>>> possible to achieve a state even close to optimal. I know folks
>>> often complain about EMF's lack of documentation for example, but my
>>> sympathy in this regard is somewhat limited (and I quietly take
>>> satisfaction from this being the biggest complaint rather than bugs
>>> or other quality issues). Certainly there is ample opportunity for
>>> the community to contribute in this regard, but that suggestion
>>> usually silences the critics quite effectively, which of course
>>> misses the point entirely...
>>>
>>> So while I'm sure a lot of people would share your view, including
>>> me, it's not so clear how to make changes happen with limited budgets
>>> and constrained resources...
>>>
>>>
>>> Volker Renneberg wrote:
>>>> Hi!
>>>>
>>>> Thanks for the link. However, I am still interested in the actual
>>>> issue of my last posting. There is a lot of information around
>>>> Eclipse available in all different types of media formats (books,
>>>> articles, etc). Since user adoption of Eclipse as a development
>>>> platform, application framework, enterprise framework, etc. really
>>>> depends on the documentation, I think Eclipse.org can do much
>>>> better. Currently, all the information is somehow semi-structured
>>>> based on the datatypes of information that is available. The first
>>>> of the website divides into five sub-categories with the relevant
>>>> projects.
>>>>
>>>> But below the top level structure of the first page, the strategy of
>>>> the web-page seems to be "give the user all the information that is
>>>> available" rather than "give the information the user needs to
>>>> accomplish a specific task".
>>>>
>>>> I am interested, whether there is an information management strategy
>>>> defined for the web-pages. And whether there has been user research
>>>> on how the web-page fulfills its needs.
>>>>
>>>> In my mind a more integrative and user and task oriented information
>>>> presentation is necessary on the webpage. But maybe I am alone with
>>>> this view.... I would like to invest some work on this if appreciated.
>>>>
>>>> So, what does the community think?!
>>>>
>>>> Cheers
>>>> Volker
>>>>
>>>> "Alex Blewitt" <alex_blewitt@yahoo.com> wrote
>>>> news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com...
>>>>
>>>>> I think pheonix was just a revamp of the way that the site looked,
>>>>> rather than anything grander. I don't think you'll find anything on
>>>>> there that will be of any use in your quest.
>>>>>
>>>>> Have a look at the 'getting started with eclipse plugins' series
>>>>> we've been running on EclipseZone, or the articles/tutorials on RCP
>>>>> development at www.eclipse.org/articles
>>>>
>>>>
>>>>
>>>
>>
--
Intalio, the Open Source BPMS Company
<a href="http://www.intalio.com">http://www.intalio.com</a>
<a href="http://bpms.intalio.com">Community website</a>
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47837 is a reply to message #47777] |
Fri, 03 August 2007 17:14 |
| Eclipse User |
|
|
|
Originally posted by: atoulme.intalio.com
Ed,
I couldn't resist to open a request for enhancement from your remarks.
https://bugs.eclipse.org/bugs/show_bug.cgi?id=198829
Regardign the Eclipse plugin runtime classpath issues, I opened a
request for enhancement the other day:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=198465
Please feel free to review, comment and vote if you like them.
Regards,
Antoine
Ed Merks wrote:
> Stéphane,
>
> Yes, I was hoping that would be the case too. I'm sure many people
> would be pleased to see such an effort and would provide moral support
> and perhaps even a little more than that. It's way too hard to find the
> things you need at Eclipse and often way too easy to do things wrong.
> For example, installing the Java EE package can be accomplished so
> easily with just two clicks. But when it doesn't work, people get
> frustrated. Often their install picks up a 1.4 JRE and there isn't a
> single user level message that tells them "Hey, we know you wanted Java
> EE support, but all those plugins are disabled because you must have a
> 5.0 JRE". The main download web page says a Java 5 JRE is recommended
> when in fact for the EE package its absolutely required. And while I'm
> busy being the critic, how many people need to be told to use -clean
> when they unzip something new; it's not like this is obvious, so I have
> to wonder if checking if the timestamp of the plugins folder has
> changed is really so expensive (but maybe there's a good reason this is
> a bad idea). And of course there's the ever recurring, I updated my
> classpath to fix compile errors but now my plugin doesn't run; changing
> the classpath manually for a plugin is almost a sure formula for runtime
> problems. I'm starting to feel like a harpie! I'd better stop...
>
>
> Stéphane LACRAMPE wrote:
>> Ed,
>>
>> I agree with you in the sense that in the end, it is easier (not easy)
>> to find developers who wants to contribute to an open source project
>> that resources who wants to spend time on documentation, or on
>> infrastructure, build and administration for example.
>> But what I understand from Volker last sentence is that he would be
>> willing to start some work on thinking how to organize in a better way
>> the documentation that is provided.
>> So maybe the question he is asking is : is there any appropriate place
>> in Eclipse to start this thinking on how to better organize Eclipse
>> project documentation ?
>>
>> Stephane
>>
>>
>> Ed Merks a écrit :
>>> Volker,
>>>
>>> I think a fundamental problem is that developers really like to
>>> develop and when they are also the same folks who must not only write
>>> all the documentation, but also maintain it and organize it
>>> effectively as well, time trade-offs need to be made. Guess what
>>> developer chose as their priority? This is of course short sighted
>>> since if clients can't figure out how to use it why bother developing
>>> it? Of course as developers we realize this, but constraints are
>>> what they are. The foundation itself is similarly resource
>>> constrained, so even with the best of intentions, it's just not
>>> possible to achieve a state even close to optimal. I know folks
>>> often complain about EMF's lack of documentation for example, but my
>>> sympathy in this regard is somewhat limited (and I quietly take
>>> satisfaction from this being the biggest complaint rather than bugs
>>> or other quality issues). Certainly there is ample opportunity for
>>> the community to contribute in this regard, but that suggestion
>>> usually silences the critics quite effectively, which of course
>>> misses the point entirely...
>>>
>>> So while I'm sure a lot of people would share your view, including
>>> me, it's not so clear how to make changes happen with limited budgets
>>> and constrained resources...
>>>
>>>
>>> Volker Renneberg wrote:
>>>> Hi!
>>>>
>>>> Thanks for the link. However, I am still interested in the actual
>>>> issue of my last posting. There is a lot of information around
>>>> Eclipse available in all different types of media formats (books,
>>>> articles, etc). Since user adoption of Eclipse as a development
>>>> platform, application framework, enterprise framework, etc. really
>>>> depends on the documentation, I think Eclipse.org can do much
>>>> better. Currently, all the information is somehow semi-structured
>>>> based on the datatypes of information that is available. The first
>>>> of the website divides into five sub-categories with the relevant
>>>> projects.
>>>>
>>>> But below the top level structure of the first page, the strategy of
>>>> the web-page seems to be "give the user all the information that is
>>>> available" rather than "give the information the user needs to
>>>> accomplish a specific task".
>>>>
>>>> I am interested, whether there is an information management strategy
>>>> defined for the web-pages. And whether there has been user research
>>>> on how the web-page fulfills its needs.
>>>>
>>>> In my mind a more integrative and user and task oriented information
>>>> presentation is necessary on the webpage. But maybe I am alone with
>>>> this view.... I would like to invest some work on this if appreciated.
>>>>
>>>> So, what does the community think?!
>>>>
>>>> Cheers
>>>> Volker
>>>>
>>>> "Alex Blewitt" <alex_blewitt@yahoo.com> wrote
>>>> news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com...
>>>>
>>>>> I think pheonix was just a revamp of the way that the site looked,
>>>>> rather than anything grander. I don't think you'll find anything on
>>>>> there that will be of any use in your quest.
>>>>>
>>>>> Have a look at the 'getting started with eclipse plugins' series
>>>>> we've been running on EclipseZone, or the articles/tutorials on RCP
>>>>> development at www.eclipse.org/articles
>>>>
>>>>
>>>>
>>>
>>
--
Intalio, the Open Source BPMS Company
<a href="http://www.intalio.com">http://www.intalio.com</a>
<a href="http://bpms.intalio.com">Community website</a>
|
|
| |
| Re: Documentation structure on eclipse.org and associated web sites [message #47898 is a reply to message #47718] |
Sat, 04 August 2007 06:40 |
| Eclipse User |
|
|
|
Originally posted by: chaves.inf.ufsc.nospam.br
This is kind of off-topic but the comment below prompted on me an urge
to reply:
Ed Merks wrote:
> I know folks often complain about EMF's lack of
> documentation for example, but my sympathy in this regard is somewhat
> limited (and I quietly take satisfaction from this being the biggest
> complaint rather than bugs or other quality issues). Certainly there is
> ample opportunity for the community to contribute in this regard, but
> that suggestion usually silences the critics quite effectively, which of
> course misses the point entirely...
Ed, no one can deny that you are one of the most (when not the most)
active contributors not only on the EMF but most of the modeling
newsgroups. But that is kind of telling - if babysitting from one of the
key developers is required for most things, it seems there is a problem
there. And if it is hard to get others to help, that could be another
sign that a significant learning barrier is at play.
So my suggestion would be: spend less time answering the same questions
again and again on the newsgroups, but use those questions to figure
what areas of the framework cause more difficulties to most people, and
write simple wiki topics that cover that subject (wiki topics are better
than articles, because they can be improved incrementally and encourage
participation). Also identify the key aspects of the EMF
*implementation* that would allow good developers to find their way in
the code and become apt to contribute not only in the forums but also
with code.
The EMF implementation (as any model implementation generated using EMF)
is much harder to understand than any other project in Eclipse.org I
have looked at (mostly SDK projects), because everything is meta (the
same is true for UML2, which is also based on EMF). Caching makes it
worse. It is a common notion that readability of generated code is not
relevant, as one should not be reading the code anyway. But if learning
from the code is much harder than usual, good thorough documentation (at
least of the essential mechanisms) is even more important. And a book
cannot be the main source of written information, unless is also freely
available in electronic form.
Many open source projects started by individuals or small companies
(Hibernate and Spring come to mind) have excellent freely available
documentation. And they get a lot of help from their communities. I am
pretty sure that if EMF (and other projects, such as UML2) had a lower
barrier of entry, it would attract much more contributors, able to help
in all aspects of the project.
Please take my comments as genuine constructive criticism. EMF is surely
the key piece in the modeling project, and your personal contribution
(as well from people like Kenn Hussey and others) has been essential for
its success. But lowering the barriers to participation should be the
key concern to EMF (as to many other subprojects) in order for the
Modeling project to thrive as an open source community. Bjorn
Freeman-Benson often writes about this on his blog (tag "open
development"). This is one of my favorite posts:
http://eclipse-projects.blogspot.com/2007/04/why-cant-i-cont ribute.html
The closing paragraph is very insightful:
"To me open source is about more than just making the source code
available: it's also about lowering the barriers to participation. Doing
so requires introspection and work, but the benefits when the community
participates are undeniable."
Cheers,
Rafael
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47931 is a reply to message #47898] |
Sat, 04 August 2007 13:02 |
| Eclipse User |
|
|
|
Originally posted by: merks.ca.ibm.com
This is a multi-part message in MIME format.
--------------010008000108050500030800
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Rafael,
My comments are inline below.
Rafael Chaves wrote:
> This is kind of off-topic but the comment below prompted on me an urge
> to reply:
>
> Ed Merks wrote:
>> I know folks often complain about EMF's lack of documentation for
>> example, but my sympathy in this regard is somewhat limited (and I
>> quietly take satisfaction from this being the biggest complaint
>> rather than bugs or other quality issues). Certainly there is ample
>> opportunity for the community to contribute in this regard, but that
>> suggestion usually silences the critics quite effectively, which of
>> course misses the point entirely...
>
> Ed, no one can deny that you are one of the most (when not the most)
> active contributors not only on the EMF but most of the modeling
> newsgroups. But that is kind of telling - if babysitting from one of
> the key developers is required for most things, it seems there is a
> problem there. And if it is hard to get others to help, that could be
> another sign that a significant learning barrier is at play.
You're not calling my community a bunch of babies are you? :-) I've
certainly gotten the message before that I'm being too helpful, and I'm
reluctant to admit that there must be some truth to that, but somehow my
motherly instincts kick in and you see the result... When it comes to
significant learning barriers, I'm not sure I can point to any
technology that doesn't have one of those. I had to learn Eclipse
before there was even a speck of documentation, and that never stopped
me. When I look at what the W3C spews out at an ever faster rate, not
to mention the ever changing and growing EE technology stack and the
Java language itself, I have to wonder how anyone ever gets a web
service written. And have you ever tried to read the XML Schema
specification? I'd better not get started on a different off-off-topic
rant. :-P
>
> So my suggestion would be: spend less time answering the same
> questions again and again on the newsgroups, but use those questions
> to figure what areas of the framework cause more difficulties to most
> people, and write simple wiki topics that cover that subject (wiki
> topics are better than articles, because they can be improved
> incrementally and encourage participation). Also identify the key
> aspects of the EMF *implementation* that would allow good developers
> to find their way in the code and become apt to contribute not only in
> the forums but also with code.
I've heard that suggestion too and in fact, this is why will continue to
spend so much time paying close attention to what troubles people have.
For example, it got very tiresome explaining endlessly and pointing at
documentation and FAQs for how to read and write an instance of a
generated model, despite the fact that the generated editor does
*exactly *that, so we wrote a new template that generates the minimal
working stand-alone code. The interesting thing is that folks often
(and perhaps even typically) don't read whatever you provide. They just
expect it to be self evident. Our documentation page has a lot of very
useful and simple information and our wiki is growing as well. Indeed,
some folks have been nice enough to contribute to that, so I agree that
it is a pretty cool way to encourage contribution. And I do often
(well, maybe only occasionally) try to add meaningful content to the FAQ
for those repeated questions.
>
> The EMF implementation (as any model implementation generated using
> EMF) is much harder to understand than any other project in
> Eclipse.org I have looked at (mostly SDK projects), because everything
> is meta (the same is true for UML2, which is also based on EMF).
> Caching makes it worse. It is a common notion that readability of
> generated code is not relevant, as one should not be reading the code
> anyway. But if learning from the code is much harder than usual, good
> thorough documentation (at least of the essential mechanisms) is even
> more important. And a book cannot be the main source of written
> information, unless is also freely available in electronic form.
Everything is meta? I'm not sure what that means. I'm not a big
believer that the never ending M0, M1, M2, spiral of meta levels has all
that much important meaning. I have no doubt that everything is not
meta though so clearly you exaggerate to make some point. However, that
point is lost on me. A generated model's API is effectively just a
simple beans pattern, and it's possible to suppress ever speck evidence
in the API that EMF is involved in producing it. No one seems bothered
by the getClass method on java.lang.Object spreading meta everywhere..
I'm also not sure what caching your referring to nor what it makes
worse, how it makes it worse, or what the alternative would be if there
were no caching. Maybe you're referring to the resource APIs, but those
seem an order of magnitude simpler than the platform's workspace APIs.
In any case, complexity is in the eye of the beholder. Newbies say they
want simple but experts want more and more capabilities, so I
fundamentally believe that what people really need is rich, orderly
complexity.
While I can agree that most of what you say is true to an extent, I'm
horrified by the comment that readability of code is not relevant.
Surely you jest?! :-( Code should be a thing of beauty to be admired
and read carefully again and again. Dave just spent an entire year
writing a new edition of the book (while EMF rapidly changed to support
Java 5.0), so we are certainly are taking documentation seriously. But
if that's not good enough because it's not free, that's unfortunate but
cannot be helped. If the community is not willing to contribute more
documentation, then it will have to spend a few dollars or make due with
what is provided by my vanishingly small team. We're software
developers, not full time information developers. Poor Dave...
>
> Many open source projects started by individuals or small companies
> (Hibernate and Spring come to mind) have excellent freely available
> documentation. And they get a lot of help from their communities. I am
> pretty sure that if EMF (and other projects, such as UML2) had a lower
> barrier of entry, it would attract much more contributors, able to
> help in all aspects of the project.
EMF is attracting many contributors and you'll find there are many
articles written by others. In fact, it's very exciting to see the
growth of EMFT and it's even more exciting and especially rewarding to
see how Modeling project has taken shape so quickly with key
technologies like GMF and GMT adding so much additional value. The core
EMF team is now dwarfed by the size of the modeling project as a whole
and is certainly not big compared to the incubating components in EMFT
that will eventually become part of EMF. Just compare the set of
contributors in each:
<http://www.eclipse.org/modeling/emf/project-info/team.php>
http://www.eclipse.org/modeling/emf/project-info/team.php
http://www.eclipse.org/modeling/emft/project-info/team.php
>
> Please take my comments as genuine constructive criticism. EMF is
> surely the key piece in the modeling project, and your personal
> contribution (as well from people like Kenn Hussey and others) has
> been essential for its success. But lowering the barriers to
> participation should be the key concern to EMF (as to many other
> subprojects) in order for the Modeling project to thrive as an open
> source community. Bjorn Freeman-Benson often writes about this on his
> blog (tag "open development"). This is one of my favorite posts:
>
> http://eclipse-projects.blogspot.com/2007/04/why-cant-i-cont ribute.html
>
Well, I'm human, so I'm not all that fond of criticism, even the
constructive kind. :-) I really don't see there being a significant
barrier to participation in the modeling project nor in EMF. I see it
growing rapidly and I see something like a book, which presents a
complete end-to-end picture, as a key to lowering the knowledge
barrier. Folks who cannot part with a few dollars are setting up their
own arbitrary barriers (although my sympathies do go out to those in
less affluent parts of the world where $50 is a real barrier). It
seems unlikely that someone unwilling to part with a few of their
dollars would ever contribute a significant amount of their equally
valuable time anyway. Certainly we've gone out of our way to write
simple step by step tutorials, simple introductory overviews, articles,
references material, and so on, not to mention that fact that we
generate a fully functional client-specific application that runs at the
press of a button. I doubt there are many examples where so much is
done by so few. But it's just never enough (that's human nature at work
again) and the more information there is, the more finding things that
are definitely there becomes a problem as well.
> The closing paragraph is very insightful:
>
> "To me open source is about more than just making the source code
> available: it's also about lowering the barriers to participation.
> Doing so requires introspection and work, but the benefits when the
> community participates are undeniable."
I totally agree. I think that the modeling project is a model of
diversity (nice play on words hey?) and I'd like to think that I helped
play some very small part in that, despite many of the legitimate
criticisms you raise. It's just human nature to believe that the
behaviors that have gotten use to where we are today are effective
behaviors that we ought to continue in the future. So while many will
think it's beneath me or them to spend time answering entry level
questions on the newsgroups, I don't agree.
>
> Cheers,
>
> Rafael
>
--------------010008000108050500030800
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
Rafael,<br>
<br>
My comments are inline below.<br>
<br>
Rafael Chaves wrote:
<blockquote cite="mid:f9170d$324$1@build.eclipse.org" type="cite">This
is kind of off-topic but the comment below prompted on me an urge to
reply:
<br>
<br>
Ed Merks wrote:
<br>
<blockquote type="cite">I know folks often complain about EMF's lack
of documentation for example, but my sympathy in this regard is
somewhat limited (and I quietly take satisfaction from this being the
biggest complaint rather than bugs or other quality issues). Certainly
there is ample opportunity for the community to contribute in this
regard, but that suggestion usually silences the critics quite
effectively, which of course misses the point entirely...
<br>
</blockquote>
<br>
Ed, no one can deny that you are one of the most (when not the most)
active contributors not only on the EMF but most of the modeling
newsgroups. But that is kind of telling - if babysitting from one of
the key developers is required for most things, it seems there is a
problem there. And if it is hard to get others to help, that could be
another sign that a significant learning barrier is at play.
<br>
</blockquote>
You're not calling my community a bunch of babies are you? :-) I've
certainly gotten the message before that I'm being too helpful, and I'm
reluctant to admit that there must be some truth to that, but somehow
my motherly instincts kick in and you see the result... When it comes
to significant learning barriers, I'm not sure I can point to any
technology that doesn't have one of those. I had to learn Eclipse
before there was even a speck of documentation, and that never stopped
me. When I look at what the W3C spews out at an ever faster rate, not
to mention the ever changing and growing EE technology stack and the
Java language itself, I have to wonder how anyone ever gets a web
service written. And have you ever tried to read the XML Schema
specification? I'd better not get started on a different off-off-topic
rant. :-P<br>
<blockquote cite="mid:f9170d$324$1@build.eclipse.org" type="cite"><br>
So my suggestion would be: spend less time answering the same questions
again and again on the newsgroups, but use those questions to figure
what areas of the framework cause more difficulties to most people, and
write simple wiki topics that cover that subject (wiki topics are
better than articles, because they can be improved incrementally and
encourage participation). Also identify the key aspects of the EMF
*implementation* that would allow good developers to find their way in
the code and become apt to contribute not only in the forums but also
with code.
<br>
</blockquote>
I've heard that suggestion too and in fact, this is why will continue
to spend so much time paying close attention to what troubles people
have. For example, it got very tiresome explaining endlessly and
pointing at documentation and FAQs for how to read and write an
instance of a generated model, despite the fact that the generated
editor does <b>exactly </b>that, so we wrote a new template that
generates the minimal working stand-alone code. The interesting thing
is that folks often (and perhaps even typically) don't read whatever
you provide. They just expect it to be self evident. Our
documentation page has a lot of very useful and simple information and
our wiki is growing as well. Indeed, some folks have been nice enough
to contribute to that, so I agree that it is a pretty cool way to
encourage contribution. And I do often (well, maybe only occasionally)
try to add meaningful content to the FAQ for those repeated questions.
<br>
<blockquote cite="mid:f9170d$324$1@build.eclipse.org" type="cite"><br>
The EMF implementation (as any model implementation generated using
EMF) is much harder to understand than any other project in Eclipse.org
I have looked at (mostly SDK projects), because everything is meta (the
same is true for UML2, which is also based on EMF). Caching makes it
worse. It is a common notion that readability of generated code is not
relevant, as one should not be reading the code anyway. But if learning
from the code is much harder than usual, good thorough documentation
(at least of the essential mechanisms) is even more important. And a
book cannot be the main source of written information, unless is also
freely available in electronic form.
<br>
</blockquote>
Everything is meta? I'm not sure what that means. I'm not a big
believer that the never ending M0, M1, M2, spiral of meta levels has
all that much important meaning. I have no doubt that everything is
not meta though so clearly you exaggerate to make some point. However,
that point is lost on me. A generated model's API is effectively just
a simple beans pattern, and it's possible to suppress ever speck
evidence in the API that EMF is involved in producing it. No one seems
bothered by the getClass method on java.lang.Object spreading meta
everywhere.. I'm also not sure what caching your referring to nor what
it makes worse, how it makes it worse, or what the alternative would be
if there were no caching. Maybe you're referring to the resource APIs,
but those seem an order of magnitude simpler than the platform's
workspace APIs. In any case, complexity is in the eye of the
beholder. Newbies say they want simple but experts want more and more
capabilities, so I fundamentally believe that what people really need
is rich, orderly complexity.<br>
<br>
While I can agree that most of what you say is true to an extent, I'm
horrified by the comment that readability of code is not relevant.
Surely you jest?! :-( Code should be a thing of beauty to be admired
and read carefully again and again. Dave just spent an entire year
writing a new edition of the book (while EMF rapidly changed to support
Java 5.0), so we are certainly are taking documentation seriously. But
if that's not good enough because it's not free, that's unfortunate but
cannot be helped. If the community is not willing to contribute more
documentation, then it will have to spend a few dollars or make due
with what is provided by my vanishingly small team. We're software
developers, not full time information developers. Poor Dave...<br>
<blockquote cite="mid:f9170d$324$1@build.eclipse.org" type="cite"><br>
Many open source projects started by individuals or small companies
(Hibernate and Spring come to mind) have excellent freely available
documentation. And they get a lot of help from their communities. I am
pretty sure that if EMF (and other projects, such as UML2) had a lower
barrier of entry, it would attract much more contributors, able to help
in all aspects of the project.
<br>
</blockquote>
EMF is attracting many contributors and you'll find there are many
articles written by others. In fact, it's very exciting to see the
growth of EMFT and it's even more exciting and especially rewarding to
see how Modeling project has taken shape so quickly with key
technologies like GMF and GMT adding so much additional value. The
core EMF team is now dwarfed by the size of the modeling
project as a whole and is certainly not big compared to the incubating
components in EMFT that will eventually become part of EMF. Just
compare the set of contributors in each:<a
href="http://www.eclipse.org/modeling/emf/project-info/team.php"><br>
</a>
<blockquote><a
href="http://www.eclipse.org/modeling/emf/project-info/team.php">http://www.eclipse.org/modeling/emf/project-info/team.php</a><br>
<a href="http://www.eclipse.org/modeling/emft/project-info/team.php">http://www.eclipse.org/modeling/emft/project-info/team.php</a></blockquote>
<blockquote cite="mid:f9170d$324$1@build.eclipse.org" type="cite"><br>
Please take my comments as genuine constructive criticism. EMF is
surely the key piece in the modeling project, and your personal
contribution (as well from people like Kenn Hussey and others) has been
essential for its success. But lowering the barriers to participation
should be the key concern to EMF (as to many other subprojects) in
order for the Modeling project to thrive as an open source community.
Bjorn Freeman-Benson often writes about this on his blog (tag "open
development"). This is one of my favorite posts:
<br>
<br>
<a class="moz-txt-link-freetext" href=" http://eclipse-projects.blogspot.com/2007/04/why-cant-i-cont ribute.html"> http://eclipse-projects.blogspot.com/2007/04/why-cant-i-cont ribute.html</a>
<br>
<br>
</blockquote>
Well, I'm human, so I'm not all that fond of criticism, even the
constructive kind. :-) I really don't see there being a significant
barrier to participation in the modeling project nor in EMF. I see it
growing rapidly and I see something like a book, which presents a
complete end-to-end picture, as a key to lowering the knowledge
barrier. Folks who cannot part with a few dollars are setting up their
own arbitrary barriers (although my sympathies do go out to those in
less affluent parts of the world where $50 is a real barrier). It
seems unlikely that someone unwilling to part with a few of their
dollars would ever contribute a significant amount of their equally
valuable time anyway. Certainly we've gone out of our way to write
simple step by step tutorials, simple introductory overviews, articles,
references material, and so on, not to mention that fact that we
generate a fully functional client-specific application that runs at
the press of a button. I doubt there are many examples where so much
is done by so few. But it's just never enough (that's human nature at
work again) and the more information there is, the more finding things
that are definitely there becomes a problem as well.<br>
<blockquote cite="mid:f9170d$324$1@build.eclipse.org" type="cite">The
closing paragraph is very insightful:
<br>
<br>
"To me open source is about more than just making the source code
available: it's also about lowering the barriers to participation.
Doing so requires introspection and work, but the benefits when the
community participates are undeniable."
<br>
</blockquote>
I totally agree. I think that the modeling project is a model of
diversity (nice play on words hey?) and I'd like to think that I helped
play some very small part in that, despite many of the legitimate
criticisms you raise. It's just human nature to believe that the
behaviors that have gotten use to where we are today are effective
behaviors that we ought to continue in the future. So while many will
think it's beneath me or them to spend time answering entry level
questions on the newsgroups, I don't agree.<br>
<blockquote cite="mid:f9170d$324$1@build.eclipse.org" type="cite"><br>
Cheers,
<br>
<br>
Rafael
<br>
<br>
</blockquote>
<br>
</body>
</html>
--------------010008000108050500030800--
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47960 is a reply to message #47868] |
Sat, 04 August 2007 18:01 |
| Eclipse User |
|
|
|
Originally posted by: eclipse5.rizzoweb.com
Volker Renneberg wrote:
> Hi there!
>
> It looks like there are some shared issues. I am willing to invest time into
> this issue. I am out for the weekend but on Monday or Tuesday I think I have
> the time to compile some issues and ideas.
I think Wiki should be considered first as the delivery medium for a
"documentation re-organization and enhancement" effort. Eclipse already
has a wiki but even someone like me, who usually knows exactly what he
is looking for, finds it to be sadly inadequate. The medium is good, but
the content and organization need work.
Eric
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #47989 is a reply to message #47931] |
Sat, 04 August 2007 21:03 |
| Eclipse User |
|
|
|
Originally posted by: chaves.inf.ufsc.nospam.br
Ed,
Re: newsgroups being less valuable for building a community than
writing more docs - it is just a matter of scale (newsposts are 1-to-1
or 1-to-few, whereas wikis are few-to-many), volatility (newsposts are
soon lost in the archive, are hard to be resumed a year later, whereas
wiki topics can evolve incrementally), cohesiveness/organization
(instead of looking for the important bits of info across different
posts in one or more threads, whereas good wiki topics tend to evolve to
a cross-reference filled, article-like form, while still being dynamic).
My take is that 15 mins of work on growing/improving the wiki is worth
at least half an hour of responding to questions on the newsgroups in
terms of community building. It takes less time, and provides more value
in the long run. A good approach could be: "just realized we didn't have
any doc on this up to now, so I sketched this wiki topic: <link>. Please
take a look and tell me if it answers your question. Others, please feel
free to jump in and help improving it" . Again, I am not suggesting more
articles or specs that take a long time to be written, instead that
important information that should be known by everybody to be spelled
out in the most direct way possible. With time, there will be
opportunity for enhancements such as examples and further explanation,
hopefully contributed by different people.
Re: EMF code being harder to follow than regular Java code. By "meta" I
guess I wanted to mean "generic". That results in extensive use of
switches and constants instead of proper specific attributes and
operations. But I guess you cannot help it because that being generic is
the inner value of the ECore API. Also, I was referring to the cache
adapter used extensively in UML2, which I now know is not an EMF thing,
mostly because my only contact with EMF is through UML2. My apologies.
> While I can agree that most of what you say is true to an extent, I'm
> horrified by the comment that readability of code is not relevant.
Re: generated code and readability - my point here was that there is the
notion that for generated code, given the productivity gains, one often
finds more important that it does the right thing and is as efficient as
possible than it is easy to read and maintain (because it ideally should
not need to be maintained, at least not directly). Again, I might just
be being influenced by my experience with UML2. Not sure how things are
with other EMF-based projects.
Re: a book as the only documentation and cheapskates - what I am
advocating for is that for an open source project it is essential that
the relevant information has to be freely and easily available to
everyone (and that means online). The value of books is that they are an
improvement on the freely available documentation because they are more
enjoyable to read, make it easier to learn, or have many well devised
examples, or insightful advices, and many Eclipse committers have
authored books. It makes learning faster. But the book should not be the
only repository of essential reference information. At least not for an
open source project that wants to encourage community participation. The
only excuse for that would be the case of the unpaid programmer for whom
the book is the only/main income it can get from his open source project.
This is from someone who never had to buy a book as a condition to
effectively use many different open source projects before (but have
bought a few still). At the same time, the level of participation on
forums by key developers is higher in EMF or UML2 newsgroups than I have
ever seen elsewhere. My whole point was that I believe these two facts
are related, and have to do with the mindset of the development team and
whether there is a honest interest in having others making significant
contributions to the project and increasingly sharing ownership. The
fact that it is feasible to contribute is not the point. The real issue
should be whether lowering the barriers to contribution is a constant
concern in the team mindset.
Again, my intention here is still of giving constructive feedback from
the point of view of a user that is grateful for having great tools such
as UML2 and EMF freely available. What you do from this feedback is
really up to you.
Cheers,
Rafael
Ed Merks wrote:
> Rafael,
>
> My comments are inline below.
>
> Rafael Chaves wrote:
>> This is kind of off-topic but the comment below prompted on me an urge
>> to reply:
>>
>> Ed Merks wrote:
>>> I know folks often complain about EMF's lack of documentation for
>>> example, but my sympathy in this regard is somewhat limited (and I
>>> quietly take satisfaction from this being the biggest complaint
>>> rather than bugs or other quality issues). Certainly there is ample
>>> opportunity for the community to contribute in this regard, but that
>>> suggestion usually silences the critics quite effectively, which of
>>> course misses the point entirely...
>>
>> Ed, no one can deny that you are one of the most (when not the most)
>> active contributors not only on the EMF but most of the modeling
>> newsgroups. But that is kind of telling - if babysitting from one of
>> the key developers is required for most things, it seems there is a
>> problem there. And if it is hard to get others to help, that could be
>> another sign that a significant learning barrier is at play.
> You're not calling my community a bunch of babies are you? :-) I've
> certainly gotten the message before that I'm being too helpful, and I'm
> reluctant to admit that there must be some truth to that, but somehow my
> motherly instincts kick in and you see the result... When it comes to
> significant learning barriers, I'm not sure I can point to any
> technology that doesn't have one of those. I had to learn Eclipse
> before there was even a speck of documentation, and that never stopped
> me. When I look at what the W3C spews out at an ever faster rate, not
> to mention the ever changing and growing EE technology stack and the
> Java language itself, I have to wonder how anyone ever gets a web
> service written. And have you ever tried to read the XML Schema
> specification? I'd better not get started on a different off-off-topic
> rant. :-P
>>
>> So my suggestion would be: spend less time answering the same
>> questions again and again on the newsgroups, but use those questions
>> to figure what areas of the framework cause more difficulties to most
>> people, and write simple wiki topics that cover that subject (wiki
>> topics are better than articles, because they can be improved
>> incrementally and encourage participation). Also identify the key
>> aspects of the EMF *implementation* that would allow good developers
>> to find their way in the code and become apt to contribute not only in
>> the forums but also with code.
> I've heard that suggestion too and in fact, this is why will continue to
> spend so much time paying close attention to what troubles people have.
> For example, it got very tiresome explaining endlessly and pointing at
> documentation and FAQs for how to read and write an instance of a
> generated model, despite the fact that the generated editor does
> *exactly *that, so we wrote a new template that generates the minimal
> working stand-alone code. The interesting thing is that folks often
> (and perhaps even typically) don't read whatever you provide. They just
> expect it to be self evident. Our documentation page has a lot of very
> useful and simple information and our wiki is growing as well. Indeed,
> some folks have been nice enough to contribute to that, so I agree that
> it is a pretty cool way to encourage contribution. And I do often
> (well, maybe only occasionally) try to add meaningful content to the FAQ
> for those repeated questions.
>>
>> The EMF implementation (as any model implementation generated using
>> EMF) is much harder to understand than any other project in
>> Eclipse.org I have looked at (mostly SDK projects), because everything
>> is meta (the same is true for UML2, which is also based on EMF).
>> Caching makes it worse. It is a common notion that readability of
>> generated code is not relevant, as one should not be reading the code
>> anyway. But if learning from the code is much harder than usual, good
>> thorough documentation (at least of the essential mechanisms) is even
>> more important. And a book cannot be the main source of written
>> information, unless is also freely available in electronic form.
> Everything is meta? I'm not sure what that means. I'm not a big
> believer that the never ending M0, M1, M2, spiral of meta levels has all
> that much important meaning. I have no doubt that everything is not
> meta though so clearly you exaggerate to make some point. However, that
> point is lost on me. A generated model's API is effectively just a
> simple beans pattern, and it's possible to suppress ever speck evidence
> in the API that EMF is involved in producing it. No one seems bothered
> by the getClass method on java.lang.Object spreading meta everywhere..
> I'm also not sure what caching your referring to nor what it makes
> worse, how it makes it worse, or what the alternative would be if there
> were no caching. Maybe you're referring to the resource APIs, but those
> seem an order of magnitude simpler than the platform's workspace APIs.
> In any case, complexity is in the eye of the beholder. Newbies say they
> want simple but experts want more and more capabilities, so I
> fundamentally believe that what people really need is rich, orderly
> complexity.
>
> While I can agree that most of what you say is true to an extent, I'm
> horrified by the comment that readability of code is not relevant.
> Surely you jest?! :-( Code should be a thing of beauty to be admired
> and read carefully again and again. Dave just spent an entire year
> writing a new edition of the book (while EMF rapidly changed to support
> Java 5.0), so we are certainly are taking documentation seriously. But
> if that's not good enough because it's not free, that's unfortunate but
> cannot be helped. If the community is not willing to contribute more
> documentation, then it will have to spend a few dollars or make due with
> what is provided by my vanishingly small team. We're software
> developers, not full time information developers. Poor Dave...
>>
>> Many open source projects started by individuals or small companies
>> (Hibernate and Spring come to mind) have excellent freely available
>> documentation. And they get a lot of help from their communities. I am
>> pretty sure that if EMF (and other projects, such as UML2) had a lower
>> barrier of entry, it would attract much more contributors, able to
>> help in all aspects of the project.
> EMF is attracting many contributors and you'll find there are many
> articles written by others. In fact, it's very exciting to see the
> growth of EMFT and it's even more exciting and especially rewarding to
> see how Modeling project has taken shape so quickly with key
> technologies like GMF and GMT adding so much additional value. The core
> EMF team is now dwarfed by the size of the modeling project as a whole
> and is certainly not big compared to the incubating components in EMFT
> that will eventually become part of EMF. Just compare the set of
> contributors in each:
> <http://www.eclipse.org/modeling/emf/project-info/team.php>
>
> http://www.eclipse.org/modeling/emf/project-info/team.php
> http://www.eclipse.org/modeling/emft/project-info/team.php
>
>>
>> Please take my comments as genuine constructive criticism. EMF is
>> surely the key piece in the modeling project, and your personal
>> contribution (as well from people like Kenn Hussey and others) has
>> been essential for its success. But lowering the barriers to
>> participation should be the key concern to EMF (as to many other
>> subprojects) in order for the Modeling project to thrive as an open
>> source community. Bjorn Freeman-Benson often writes about this on his
>> blog (tag "open development"). This is one of my favorite posts:
>>
>> http://eclipse-projects.blogspot.com/2007/04/why-cant-i-cont ribute.html
>>
> Well, I'm human, so I'm not all that fond of criticism, even the
> constructive kind. :-) I really don't see there being a significant
> barrier to participation in the modeling project nor in EMF. I see it
> growing rapidly and I see something like a book, which presents a
> complete end-to-end picture, as a key to lowering the knowledge
> barrier. Folks who cannot part with a few dollars are setting up their
> own arbitrary barriers (although my sympathies do go out to those in
> less affluent parts of the world where $50 is a real barrier). It
> seems unlikely that someone unwilling to part with a few of their
> dollars would ever contribute a significant amount of their equally
> valuable time anyway. Certainly we've gone out of our way to write
> simple step by step tutorials, simple introductory overviews, articles,
> references material, and so on, not to mention that fact that we
> generate a fully functional client-specific application that runs at the
> press of a button. I doubt there are many examples where so much is
> done by so few. But it's just never enough (that's human nature at work
> again) and the more information there is, the more finding things that
> are definitely there becomes a problem as well.
>> The closing paragraph is very insightful:
>>
>> "To me open source is about more than just making the source code
>> available: it's also about lowering the barriers to participation.
>> Doing so requires introspection and work, but the benefits when the
>> community participates are undeniable."
> I totally agree. I think that the modeling project is a model of
> diversity (nice play on words hey?) and I'd like to think that I helped
> play some very small part in that, despite many of the legitimate
> criticisms you raise. It's just human nature to believe that the
> behaviors that have gotten use to where we are today are effective
> behaviors that we ought to continue in the future. So while many will
> think it's beneath me or them to spend time answering entry level
> questions on the newsgroups, I don't agree.
>>
>> Cheers,
>>
>> Rafael
>>
>
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #48023 is a reply to message #47989] |
Sat, 04 August 2007 22:34 |
| Eclipse User |
|
|
|
Originally posted by: merks.ca.ibm.com
Rafael,
More comments below. Hopefully my rum swizzler won't result in too much
nonsense or too many typos. :-P
Rafael Chaves wrote:
> Ed,
>
> Re: newsgroups being less valuable for building a community than
> writing more docs - it is just a matter of scale (newsposts are 1-to-1
> or 1-to-few, whereas wikis are few-to-many), volatility (newsposts are
> soon lost in the archive, are hard to be resumed a year later, whereas
> wiki topics can evolve incrementally), cohesiveness/organization
> (instead of looking for the important bits of info across different
> posts in one or more threads, whereas good wiki topics tend to evolve
> to a cross-reference filled, article-like form, while still being
> dynamic). My take is that 15 mins of work on growing/improving the
> wiki is worth at least half an hour of responding to questions on the
> newsgroups in terms of community building. It takes less time, and
> provides more value in the long run. A good approach could be: "just
> realized we didn't have any doc on this up to now, so I sketched this
> wiki topic: <link>. Please take a look and tell me if it answers your
> question. Others, please feel free to jump in and help improving it" .
> Again, I am not suggesting more articles or specs that take a long
> time to be written, instead that important information that should be
> known by everybody to be spelled out in the most direct way possible.
> With time, there will be opportunity for enhancements such as examples
> and further explanation, hopefully contributed by different people.
You sound like Nick. :-) I'm sure adding wiki content is even much
better than a 1:2 ratio. I'll try to do better...
>
> Re: EMF code being harder to follow than regular Java code. By "meta"
> I guess I wanted to mean "generic". That results in extensive use of
> switches and constants instead of proper specific attributes and
> operations. But I guess you cannot help it because that being generic
> is the inner value of the ECore API. Also, I was referring to the
> cache adapter used extensively in UML2, which I now know is not an EMF
> thing, mostly because my only contact with EMF is through UML2. My
> apologies.
Since I'm not feeling particularly politically correct, when it comes to
things like UML2 and XML Schema, I can't help but think that the old
saying "You can't make a silk purse out of a sows ear" is applicable. :-P
>
> > While I can agree that most of what you say is true to an extent, I'm
> > horrified by the comment that readability of code is not relevant.
>
> Re: generated code and readability - my point here was that there is
> the notion that for generated code, given the productivity gains, one
> often finds more important that it does the right thing and is as
> efficient as possible than it is easy to read and maintain (because it
> ideally should not need to be maintained, at least not directly).
> Again, I might just be being influenced by my experience with UML2.
> Not sure how things are with other EMF-based projects.
>
> Re: a book as the only documentation and cheapskates - what I am
> advocating for is that for an open source project it is essential that
> the relevant information has to be freely and easily available to
> everyone (and that means online). The value of books is that they are
> an improvement on the freely available documentation because they are
> more enjoyable to read, make it easier to learn, or have many well
> devised examples, or insightful advices, and many Eclipse committers
> have authored books. It makes learning faster. But the book should not
> be the only repository of essential reference information. At least
> not for an open source project that wants to encourage community
> participation. The only excuse for that would be the case of the
> unpaid programmer for whom the book is the only/main income it can get
> from his open source project.
Certainly a book should not be the only documentation and I can't
imagine anyone ever making enough money from a book that the money would
be a primary motivator for writing one...
>
> This is from someone who never had to buy a book as a condition to
> effectively use many different open source projects before (but have
> bought a few still). At the same time, the level of participation on
> forums by key developers is higher in EMF or UML2 newsgroups than I
> have ever seen elsewhere. My whole point was that I believe these two
> facts are related, and have to do with the mindset of the development
> team and whether there is a honest interest in having others making
> significant contributions to the project and increasingly sharing
> ownership. The fact that it is feasible to contribute is not the
> point. The real issue should be whether lowering the barriers to
> contribution is a constant concern in the team mindset.
Let me assure you that it is a constant reminder when I have such a
small team. I value my community more than you could possibly imagine.
Perhaps that's one of the reason why I feel compelled to nurture it
constantly. Or at least that's what I feel like I'm doing. It might
well be that I'm stifling it like an over protective parent...
>
> Again, my intention here is still of giving constructive feedback from
> the point of view of a user that is grateful for having great tools
> such as UML2 and EMF freely available. What you do from this feedback
> is really up to you.
Yes, I think most of your criticisms are well founded...
>
> Cheers,
>
> Rafael
>
> Ed Merks wrote:
>> Rafael,
>>
>> My comments are inline below.
>>
>> Rafael Chaves wrote:
>>> This is kind of off-topic but the comment below prompted on me an
>>> urge to reply:
>>>
>>> Ed Merks wrote:
>>>> I know folks often complain about EMF's lack of documentation for
>>>> example, but my sympathy in this regard is somewhat limited (and I
>>>> quietly take satisfaction from this being the biggest complaint
>>>> rather than bugs or other quality issues). Certainly there is
>>>> ample opportunity for the community to contribute in this regard,
>>>> but that suggestion usually silences the critics quite effectively,
>>>> which of course misses the point entirely...
>>>
>>> Ed, no one can deny that you are one of the most (when not the most)
>>> active contributors not only on the EMF but most of the modeling
>>> newsgroups. But that is kind of telling - if babysitting from one of
>>> the key developers is required for most things, it seems there is a
>>> problem there. And if it is hard to get others to help, that could
>>> be another sign that a significant learning barrier is at play.
>> You're not calling my community a bunch of babies are you? :-) I've
>> certainly gotten the message before that I'm being too helpful, and
>> I'm reluctant to admit that there must be some truth to that, but
>> somehow my motherly instincts kick in and you see the result... When
>> it comes to significant learning barriers, I'm not sure I can point
>> to any technology that doesn't have one of those. I had to learn
>> Eclipse before there was even a speck of documentation, and that
>> never stopped me. When I look at what the W3C spews out at an ever
>> faster rate, not to mention the ever changing and growing EE
>> technology stack and the Java language itself, I have to wonder how
>> anyone ever gets a web service written. And have you ever tried to
>> read the XML Schema specification? I'd better not get started on a
>> different off-off-topic rant. :-P
>>>
>>> So my suggestion would be: spend less time answering the same
>>> questions again and again on the newsgroups, but use those questions
>>> to figure what areas of the framework cause more difficulties to
>>> most people, and write simple wiki topics that cover that subject
>>> (wiki topics are better than articles, because they can be improved
>>> incrementally and encourage participation). Also identify the key
>>> aspects of the EMF *implementation* that would allow good developers
>>> to find their way in the code and become apt to contribute not only
>>> in the forums but also with code.
>> I've heard that suggestion too and in fact, this is why will continue
>> to spend so much time paying close attention to what troubles people
>> have. For example, it got very tiresome explaining endlessly and
>> pointing at documentation and FAQs for how to read and write an
>> instance of a generated model, despite the fact that the generated
>> editor does *exactly *that, so we wrote a new template that generates
>> the minimal working stand-alone code. The interesting thing is that
>> folks often (and perhaps even typically) don't read whatever you
>> provide. They just expect it to be self evident. Our documentation
>> page has a lot of very useful and simple information and our wiki is
>> growing as well. Indeed, some folks have been nice enough to
>> contribute to that, so I agree that it is a pretty cool way to
>> encourage contribution. And I do often (well, maybe only
>> occasionally) try to add meaningful content to the FAQ for those
>> repeated questions.
>>>
>>> The EMF implementation (as any model implementation generated using
>>> EMF) is much harder to understand than any other project in
>>> Eclipse.org I have looked at (mostly SDK projects), because
>>> everything is meta (the same is true for UML2, which is also based
>>> on EMF). Caching makes it worse. It is a common notion that
>>> readability of generated code is not relevant, as one should not be
>>> reading the code anyway. But if learning from the code is much
>>> harder than usual, good thorough documentation (at least of the
>>> essential mechanisms) is even more important. And a book cannot be
>>> the main source of written information, unless is also freely
>>> available in electronic form.
>> Everything is meta? I'm not sure what that means. I'm not a big
>> believer that the never ending M0, M1, M2, spiral of meta levels has
>> all that much important meaning. I have no doubt that everything is
>> not meta though so clearly you exaggerate to make some point.
>> However, that point is lost on me. A generated model's API is
>> effectively just a simple beans pattern, and it's possible to
>> suppress ever speck evidence in the API that EMF is involved in
>> producing it. No one seems bothered by the getClass method on
>> java.lang.Object spreading meta everywhere.. I'm also not sure what
>> caching your referring to nor what it makes worse, how it makes it
>> worse, or what the alternative would be if there were no caching.
>> Maybe you're referring to the resource APIs, but those seem an order
>> of magnitude simpler than the platform's workspace APIs. In any
>> case, complexity is in the eye of the beholder. Newbies say they
>> want simple but experts want more and more capabilities, so I
>> fundamentally believe that what people really need is rich, orderly
>> complexity.
>>
>> While I can agree that most of what you say is true to an extent, I'm
>> horrified by the comment that readability of code is not relevant.
>> Surely you jest?! :-( Code should be a thing of beauty to be
>> admired and read carefully again and again. Dave just spent an
>> entire year writing a new edition of the book (while EMF rapidly
>> changed to support Java 5.0), so we are certainly are taking
>> documentation seriously. But if that's not good enough because it's
>> not free, that's unfortunate but cannot be helped. If the community
>> is not willing to contribute more documentation, then it will have to
>> spend a few dollars or make due with what is provided by my
>> vanishingly small team. We're software developers, not full time
>> information developers. Poor Dave...
>>>
>>> Many open source projects started by individuals or small companies
>>> (Hibernate and Spring come to mind) have excellent freely available
>>> documentation. And they get a lot of help from their communities. I
>>> am pretty sure that if EMF (and other projects, such as UML2) had a
>>> lower barrier of entry, it would attract much more contributors,
>>> able to help in all aspects of the project.
>> EMF is attracting many contributors and you'll find there are many
>> articles written by others. In fact, it's very exciting to see the
>> growth of EMFT and it's even more exciting and especially rewarding
>> to see how Modeling project has taken shape so quickly with key
>> technologies like GMF and GMT adding so much additional value. The
>> core EMF team is now dwarfed by the size of the modeling project as a
>> whole and is certainly not big compared to the incubating components
>> in EMFT that will eventually become part of EMF. Just compare the
>> set of contributors in each:
>> <http://www.eclipse.org/modeling/emf/project-info/team.php>
>>
>> http://www.eclipse.org/modeling/emf/project-info/team.php
>> http://www.eclipse.org/modeling/emft/project-info/team.php
>>
>>>
>>> Please take my comments as genuine constructive criticism. EMF is
>>> surely the key piece in the modeling project, and your personal
>>> contribution (as well from people like Kenn Hussey and others) has
>>> been essential for its success. But lowering the barriers to
>>> participation should be the key concern to EMF (as to many other
>>> subprojects) in order for the Modeling project to thrive as an open
>>> source community. Bjorn Freeman-Benson often writes about this on
>>> his blog (tag "open development"). This is one of my favorite posts:
>>>
>>> http://eclipse-projects.blogspot.com/2007/04/why-cant-i-cont ribute.html
>>>
>> Well, I'm human, so I'm not all that fond of criticism, even the
>> constructive kind. :-) I really don't see there being a significant
>> barrier to participation in the modeling project nor in EMF. I see
>> it growing rapidly and I see something like a book, which presents a
>> complete end-to-end picture, as a key to lowering the knowledge
>> barrier. Folks who cannot part with a few dollars are setting up
>> their own arbitrary barriers (although my sympathies do go out to
>> those in less affluent parts of the world where $50 is a real
>> barrier). It seems unlikely that someone unwilling to part with a
>> few of their dollars would ever contribute a significant amount of
>> their equally valuable time anyway. Certainly we've gone out of our
>> way to write simple step by step tutorials, simple introductory
>> overviews, articles, references material, and so on, not to mention
>> that fact that we generate a fully functional client-specific
>> application that runs at the press of a button. I doubt there are
>> many examples where so much is done by so few. But it's just never
>> enough (that's human nature at work again) and the more information
>> there is, the more finding things that are definitely there becomes a
>> problem as well.
>>> The closing paragraph is very insightful:
>>>
>>> "To me open source is about more than just making the source code
>>> available: it's also about lowering the barriers to participation.
>>> Doing so requires introspection and work, but the benefits when the
>>> community participates are undeniable."
>> I totally agree. I think that the modeling project is a model of
>> diversity (nice play on words hey?) and I'd like to think that I
>> helped play some very small part in that, despite many of the
>> legitimate criticisms you raise. It's just human nature to believe
>> that the behaviors that have gotten use to where we are today are
>> effective behaviors that we ought to continue in the future. So
>> while many will think it's beneath me or them to spend time answering
>> entry level questions on the newsgroups, I don't agree.
>>>
>>> Cheers,
>>>
>>> Rafael
>>>
>>
|
|
|
| Re: Documentation structure on eclipse.org and associated web sites [message #48054 is a reply to message #47989] |
Sun, 05 August 2007 19:39 |
| Eclipse User |
|
|
|
Originally posted by: jacek.pospychala.pl.ibm.com
Rafael,
I would say, that only specific thing to EMF group and Ed, is that he
answers so fast. But the fact that there are developers answering, is
nothing special - on platform there are guys like Paul Webster who often
answer all bits of platform internals, or tptp (which lot people find
difficult to use) has quite a lot developers on their group too. If they
don't answer so much, It doesn't mean that they have better
documentation. Maybe they are busy with other things. Then it appears,
that in fact not only a dev can answer a certain question, but someone
else in community too. The same with EMF, when Ed is away, questions are
still answered, so no babysitting is required. I also think that EMF
group is sometimes simply overused - it's easier to ask than search by
yourself. Even more, you may get some comments on your ideas, which you
wouldn't get using search.
In fact, the answers like you suggest "just realized we didn't have any
doc..." are often seen as Ed's words "If you look into EMF code, we do
it like this <code>".
So it means, that one just didn't get into the right place before asking
question. Rewriting it to wiki would mean reproducing a bunch of code :)
However, maybe rephrasing would be good. But then there would have to
be a separate answer for every case, making wiki too big to search, or
answers should be more abstract, which in turn would make them hard to
understand the same way as with code. Maybe more samples? I am lively
interested in EMF (but not related with team) and some time ago I was
thinking of improving the docs about customizing editor - which in my
opinion is one of most asked questions. Soon I realized that lot things
are actually rather platform-specific and on emf side the most
troublesome is xyz.edit providers mechanism. But yes, maybe now is good
time to start it...
I think the feeling that EMF is difficult comes rather from the fact,
that we're always not sure, how much of what we want it supports, but at
the same time we're too much focused on our own project's needs to see
all the use cases that a generic library has to cover. Then indeed
things look hard to understand.
Rafael Chaves wrote:
> Ed,
>
> Re: newsgroups being less valuable for building a community than
> writing more docs - it is just a matter of scale (newsposts are 1-to-1
> or 1-to-few, whereas wikis are few-to-many), volatility (newsposts are
> soon lost in the archive, are hard to be resumed a year later, whereas
> wiki topics can evolve incrementally), cohesiveness/organization
> (instead of looking for the important bits of info across different
> posts in one or more threads, whereas good wiki topics tend to evolve
> to a cross-reference filled, article-like form, while still being
> dynamic). My take is that 15 mins of work on growing/improving the
> wiki is worth at least half an hour of responding to questions on the
> newsgroups in terms of community building. It takes less time, and
> provides more value in the long run. A good approach could be: "just
> realized we didn't have any doc on this up to now, so I sketched this
> wiki topic: <link>. Please take a look and tell me if it answers your
> question. Others, please feel free to jump in and help improving it" .
> Again, I am not suggesting more articles or specs that take a long
> time to be written, instead that important information that should be
> known by everybody to be spelled out in the most direct way possible.
> With time, there will be opportunity for enhancements such as examples
> and further explanation, hopefully contributed by different people.
>
> Re: EMF code being harder to follow than regular Java code. By "meta"
> I guess I wanted to mean "generic". That results in extensive use of
> switches and constants instead of proper specific attributes and
> operations. But I guess you cannot help it because that being generic
> is the inner value of the ECore API. Also, I was referring to the
> cache adapter used extensively in UML2, which I now know is not an EMF
> thing, mostly because my only contact with EMF is through UML2. My
> apologies.
>
> > While I can agree that most of what you say is true to an extent, I'm
> > horrified by the comment that readability of code is not relevant.
>
> Re: generated code and readability - my point here was that there is
> the notion that for generated code, given the productivity gains, one
> often finds more important that it does the right thing and is as
> efficient as possible than it is easy to read and maintain (because it
> ideally should not need to be maintained, at least not directly).
> Again, I might just be being influenced by my experience with UML2.
> Not sure how things are with other EMF-based projects.
>
> Re: a book as the only documentation and cheapskates - what I am
> advocating for is that for an open source project it is essential that
> the relevant information has to be freely and easily available to
> everyone (and that means online). The value of books is that they are
> an improvement on the freely available documentation because they are
> more enjoyable to read, make it easier to learn, or have many well
> devised examples, or insightful advices, and many Eclipse committers
> have authored books. It makes learning faster. But the book should not
> be the only repository of essential reference information. At least
> not for an open source project that wants to encourage community
> participation. The only excuse for that would be the case of the
> unpaid programmer for whom the book is the only/main income it can get
> from his open source project.
>
> This is from someone who never had to buy a book as a condition to
> effectively use many different open source projects before (but have
> bought a few still). At the same time, the level of participation on
> forums by key developers is higher in EMF or UML2 newsgroups than I
> have ever seen elsewhere. My whole point was that I believe these two
> facts are related, and have to do with the mindset of the development
> team and whether there is a honest interest in having others making
> significant contributions to the project and increasingly sharing
> ownership. The fact that it is feasible to contribute is not the
> point. The real issue should be whether lowering the barriers to
> contribution is a constant concern in the team mindset.
>
> Again, my intention here is still of giving constructive feedback from
> the point of view of a user that is grateful for having great tools
> such as UML2 and EMF freely available. What you do from this feedback
> is really up to you.
>
> Cheers,
>
> Rafael
>
> Ed Merks wrote:
>> Rafael,
>>
>> My comments are inline below.
>>
>> Rafael Chaves wrote:
>>> This is kind of off-topic but the comment below prompted on me an
>>> urge to reply:
>>>
>>> Ed Merks wrote:
>>>> I know folks often complain about EMF's lack of documentation for
>>>> example, but my sympathy in this regard is somewhat limited (and I
>>>> quietly take satisfaction from this being the biggest complaint
>>>> rather than bugs or other quality issues). Certainly there is
>>>> ample opportunity for the community to contribute in this regard,
>>>> but that suggestion usually silences the critics quite effectively,
>>>> which of course misses the point entirely...
>>>
>>> Ed, no one can deny that you are one of the most (when not the most)
>>> active contributors not only on the EMF but most of the modeling
>>> newsgroups. But that is kind of telling - if babysitting from one of
>>> the key developers is required for most things, it seems there is a
>>> problem there. And if it is hard to get others to help, that could
>>> be another sign that a significant learning barrier is at play.
>> You're not calling my community a bunch of babies are you? :-) I've
>> certainly gotten the message before that I'm being too helpful, and
>> I'm reluctant to admit that there must be some truth to that, but
>> somehow my motherly instincts kick in and you see the result... When
>> it comes to significant learning barriers, I'm not sure I can point
>> to any technology that doesn't have one of those. I had to learn
>> Eclipse before there was even a speck of documentation, and that
>> never stopped me. When I look at what the W3C spews out at an ever
>> faster rate, not to mention the ever changing and growing EE
>> technology stack and the Java language itself, I have to wonder how
>> anyone ever gets a web service written. And have you ever tried to
>> read the XML Schema specification? I'd better not get started on a
>> different off-off-topic rant. :-P
>>>
>>> So my suggestion would be: spend less time answering the same
>>> questions again and again on the newsgroups, but use those questions
>>> to figure what areas of the framework cause more difficulties to
>>> most people, and write simple wiki topics that cover that subject
>>> (wiki topics are better than articles, because they can be improved
>>> incrementally and encourage participation). Also identify the key
>>> aspects of the EMF *implementation* that would allow good developers
>>> to find their way in the code and become apt to contribute not only
>>> in the forums but also with code.
>> I've heard that suggestion too and in fact, this is why will continue
>> to spend so much time paying close attention to what troubles people
>> have. For example, it got very tiresome explaining endlessly and
>> pointing at documentation and FAQs for how to read and write an
>> instance of a generated model, despite the fact that the generated
>> editor does *exactly *that, so we wrote a new template that generates
>> the minimal working stand-alone code. The interesting thing is that
>> folks often (and perhaps even typically) don't read whatever you
>> provide. They just expect it to be self evident. Our documentation
>> page has a lot of very useful and simple information and our wiki is
>> growing as well. Indeed, some folks have been nice enough to
>> contribute to that, so I agree that it is a pretty cool way to
>> encourage contribution. And I do often (well, maybe only
>> occasionally) try to add meaningful content to the FAQ for those
>> repeated questions.
>>>
>>> The EMF implementation (as any model implementation generated using
>>> EMF) is much harder to understand than any other project in
>>> Eclipse.org I have looked at (mostly SDK projects), because
>>> everything is meta (the same is true for UML2, which is also based
>>> on EMF). Caching makes it worse. It is a common notion that
>>> readability of generated code is not relevant, as one should not be
>>> reading the code anyway. But if learning from the code is much
>>> harder than usual, good thorough documentation (at least of the
>>> essential mechanisms) is even more important. And a book cannot be
>>> the main source of written information, unless is also freely
>>> available in electronic form.
>> Everything is meta? I'm not sure what that means. I'm not a big
>> believer that the never ending M0, M1, M2, spiral of meta levels has
>> all that much important meaning. I have no doubt that everything is
>> not meta though so clearly you exaggerate to make some point.
>> However, that point is lost on me. A generated model's API is
>> effectively just a simple beans pattern, and it's possible to
>> suppress ever speck evidence in the API that EMF is involved in
>> producing it. No one seems bothered by the getClass method on
>> java.lang.Object spreading meta everywhere.. I'm also not sure what
>> caching your referring to nor what it makes worse, how it makes it
>> worse, or what the alternative would be if there were no caching.
>> Maybe you're referring to the resource APIs, but those seem an order
>> of magnitude simpler than the platform's workspace APIs. In any
>> case, complexity is in the eye of the beholder. Newbies say they
>> want simple but experts want more and more capabilities, so I
>> fundamentally believe that what people really need is rich, orderly
>> complexity.
>>
>> While I can agree that most of what you say is true to an extent, I'm
>> horrified by the comment that readability of code is not relevant.
>> Surely you jest?! :-( Code should be a thing of beauty to be
>> admired and read carefully again and again. Dave just spent an
>> entire year writing a new edition of the book (while EMF rapidly
>> changed to support Java 5.0), so we are certainly are taking
>> documentation seriously. But if that's not good enough because it's
>> not free, that's unfortunate but cannot be helped. If the community
>> is not willing to contribute more documentation, then it will have to
>> spend a few dollars or make due with what is provided by my
>> vanishingly small team. We're software developers, not full time
>> information developers. Poor Dave...
>>>
>>> Many open source projects started by individuals or small companies
>>> (Hibernate and Spring come to mind) have excellent freely available
>>> documentation. And they get a lot of help from their communities. I
>>> am pretty sure that if EMF (and other projects, such as UML2) had a
>>> lower barrier of entry, it would attract much more contributors,
>>> able to help in all aspects of the project.
>> EMF is attracting many contributors and you'll find there are many
>> articles written by others. In fact, it's very exciting to see the
>> growth of EMFT and it's even more exciting and especially rewarding
>> to see how Modeling project has taken shape so quickly with key
>> technologies like GMF and GMT adding so much additional value. The
>> core EMF team is now dwarfed by the size of the modeling project as a
>> whole and is certainly not big compared to the incubating components
>> in EMFT that will eventually become part of EMF. Just compare the
>> set of contributors in each:
>> <http://www.eclipse.org/modeling/emf/project-info/team.php>
>>
>> http://www.eclipse.org/modeling/emf/project-info/team.php
>> http://www.eclipse.org/modeling/emft/project-info/team.php
>>
>>>
>>> Please take my comments as genuine constructive criticism. EMF is
>>> surely the key piece in the modeling project, and your personal
>>> contribution (as well from people like Kenn Hussey and others) has
>>> been essential for its success. But lowering the barriers to
>>> participation should be the key concern to EMF (as to many other
>>> subprojects) in order for the Modeling project to thrive as an open
>>> source community. Bjorn Freeman-Benson often writes about this on
>>> his blog (tag "open development"). This is one of my favorite posts:
>>>
>>> http://eclipse-projects.blogspot.com/2007/04/why-cant-i-cont ribute.html
>>>
>> Well, I'm human, so I'm not all that fond of criticism, even the
>> constructive kind. :-) I really don't see there being a significant
>> barrier to participation in the modeling project nor in EMF. I see
>> it growing rapidly and I see something like a book, which presents a
>> complete end-to-end picture, as a key to lowering the knowledge
>> barrier. Folks who cannot part with a few dollars are setting up
>> their own arbitrary barriers (although my sympathies do go out to
>> those in less affluent parts of the world where $50 is a real
>> barrier). It seems unlikely that someone unwilling to part with a
>> few of their dollars would ever contribute a significant amount of
>> their equally valuable time anyway. Certainly we've gone out of our
>> way to write simple step by step tutorials, simple introductory
>> overviews, articles, references material, and so on, not to mention
>> that fact that we generate a fully functional client-specific
>> application that runs at the press of a button. I doubt there are
>> many examples where so much is done by so few. But it's just never
>> enough (that's human nature at work again) and the more information
>> there is, the more finding things that are definitely there becomes a
>> problem as well.
>>> The closing paragraph is very insightful:
>>>
>>> "To me open source is about more than just making the source code
>>> available: it's also about lowering the barriers to participation.
>>> Doing so requires introspection and work, but the benefits when the
>>> community participates are undeniable."
>> I totally agree. I think that the modeling project is a model of
>> diversity (nice play on words hey?) and I'd like to think that I
>> helped play some very small part in that, despite many of the
>> legitimate criticisms you raise. It's just human nature to believe
>> that the behaviors that have gotten use to where we are today are
>> effective behaviors that we ought to continue in the future. So
>> while many will think it's beneath me or them to spend time answering
>> entry level questions on the newsgroups, I don't agree.
>>>
>>> Cheers,
>>>
>>> Rafael
>>>
>>
|
|
| |
| Re: Documentation structure on eclipse.org and associated web sites [message #48890 is a reply to message #47689] |
Wed, 29 August 2007 15:52 |
Eclipse Webmaster
Messages: 607343
Registered: July 2009 |
Senior Member |
|
|
Volker Renneberg wrote:
> Hi!
>
> Thanks for the link. However, I am still interested in the actual
issue of
> my last posting.
Volker,
You inquired about this on the Phoenix project newsgroup
(eclipse.technology.phoenix). Apologies for the total silence. As the
Phoenix project lead (somewhat), I will post a reply over on the Phoenix
newsgroup shortly.
I do have answers and some documentation that may help. It's all one
big Work In Progress and a Whole Lot Of Challenges.
Thanks,
Denis
Volker Renneberg wrote:
> Hi!
>
> Thanks for the link. However, I am still interested in the actual issue of
> my last posting. There is a lot of information around Eclipse available in
> all different types of media formats (books, articles, etc). Since user
> adoption of Eclipse as a development platform, application framework,
> enterprise framework, etc. really depends on the documentation, I think
> Eclipse.org can do much better. Currently, all the information is somehow
> semi-structured based on the datatypes of information that is available. The
> first of the website divides into five sub-categories with the relevant
> projects.
>
> But below the top level structure of the first page, the strategy of the
> web-page seems to be "give the user all the information that is available"
> rather than "give the information the user needs to accomplish a specific
> task".
>
> I am interested, whether there is an information management strategy defined
> for the web-pages. And whether there has been user research on how the
> web-page fulfills its needs.
>
> In my mind a more integrative and user and task oriented information
> presentation is necessary on the webpage. But maybe I am alone with this
> view.... I would like to invest some work on this if appreciated.
>
> So, what does the community think?!
>
> Cheers
> Volker
>
> "Alex Blewitt" <alex_blewitt@yahoo.com> wrote
> news:1389408749.8151186140154609.JavaMail.root@cp9.dzone.com...
>> I think pheonix was just a revamp of the way that the site looked, rather
>> than anything grander. I don't think you'll find anything on there that
>> will be of any use in your quest.
>>
>> Have a look at the 'getting started with eclipse plugins' series we've
>> been running on EclipseZone, or the articles/tutorials on RCP development
>> at www.eclipse.org/articles
>
>
--
Eclipse WebMaster - webmaster@eclipse.org
Questions? Consult the WebMaster FAQ at
http://wiki.eclipse.org/index.php/Webmaster_FAQ
View my status at http://wiki.eclipse.org/index.php/WebMaster
|
|
|
Goto Forum:
Current Time: Tue Apr 16 08:15:29 GMT 2024
Powered by FUDForum. Page generated in 0.09686 seconds |
] 
Search
Help
Register
Login
Home
