Proper documentation ?

I think all of us saw the lack of plugins for IntelliJ. I mean just compare with the number of plugins for Eclipse.
IntelliJ is a great IDE (years ahead Eclipse), but it could be even greater with new plugins.
I think one of the reasons for the this is the lack of proper documentation (beside javadoc).
The beginners expects a tutorial - like documentation and those few are outdated (custom language tutorial is for IntelliJ 5 and a LOT has changed in OpenAPI since then; the other is for IntelliJ 4.5).
Would you please consider providing proper OpenAPI documentation?
Because, frankly, a forum is only for specific problems, not a proper place for documentation.

Also, would you like me to create a JIRA issue concerning this?

21 comments

Hello Alexander,

I think all of us saw the lack of plugins for IntelliJ. I mean just
compare with the number of plugins for Eclipse.

IntelliJ is a great IDE (years ahead Eclipse), but it could be even
greater with new plugins.

I think one of the reasons for the this is the lack of proper
documentation (beside javadoc).

The beginners expects a tutorial - like documentation and those few
are outdated (custom language tutorial is for IntelliJ 5 and a LOT has
changed in OpenAPI since then; the other is for IntelliJ 4.5).

Would you please consider providing proper OpenAPI documentation?

Because, frankly, a forum is only for specific problems, not a proper
place for documentation.

Also, would you like me to create a JIRA issue concerning this?


If it were just a matter of not having a JIRA issue, things would be really
easy. :) As you can see, we do not currently have the resources for providing
comprehensive and up-to-date documentation, and a JIRA issue will not help
us get those. Speaking very simply, good OpenAPI documentation requires a
full-time writer with very good programming skills, and people with the necessary
level of programming skills tend to prefer programming to writing.

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"


0

Let me make a suggestion (again): Have a wiki for javadoc - should be automated, so that
user edited content gets promoted to real javadoc in the next release, or maybe just
integrated into Idea's own javadoc viewer.
If only there were already such a javadoc-wiki...

I feel getting started isn't too hard.
After that common problems/solutions can be researched in existing forum threads.
It's working with the API and figuring out necessary relations and call sequences in the
OpenAPI that's tough.
I'd be happy to enhance the javadoc whenever I figured out how to do something, e.g. most
XyzManager classes do not even mention how the heck you get your hands on an instance of it.

Also it would help a lot if the standard plugins that already come with source would also
include an Idea project that you can simply open and start browsing source code
(or even better the plugin package came as/with a plugin itself that adds some menu items
to directly open these example plugin projects).

BTW the number of eclipse plugins is quite meaningless because you simply don't need that
many plugins in Idea - it includes many features by default (solidly integrated and
supported). Of course that doesn't help if your own favorite feature X is not supported by
Idea or any existing plugin.


Dmitry Jemerov wrote:

Hello Alexander,

>> I think all of us saw the lack of plugins for IntelliJ. I mean just
>> compare with the number of plugins for Eclipse.
>>
>> IntelliJ is a great IDE (years ahead Eclipse), but it could be even
>> greater with new plugins.
>>
>> I think one of the reasons for the this is the lack of proper
>> documentation (beside javadoc).
>>
>> The beginners expects a tutorial - like documentation and those few
>> are outdated (custom language tutorial is for IntelliJ 5 and a LOT has
>> changed in OpenAPI since then; the other is for IntelliJ 4.5).
>>
>> Would you please consider providing proper OpenAPI documentation?
>>
>> Because, frankly, a forum is only for specific problems, not a proper
>> place for documentation.
>>
>> Also, would you like me to create a JIRA issue concerning this?


If it were just a matter of not having a JIRA issue, things would be
really easy. :) As you can see, we do not currently have the resources
for providing comprehensive and up-to-date documentation, and a JIRA
issue will not help us get those. Speaking very simply, good OpenAPI
documentation requires a full-time writer with very good programming
skills, and people with the necessary level of programming skills tend
to prefer programming to writing.

0

Honestly, i don't think it's the lack of documentation that has been what has made plugin development much harder than it should be.
I think it's just the fact that most of the API is closed source that makes it hard compared to Eclipse or Netbeans. I find myself much more often than i'd like having to decompile code from idea.jar and trying to make some sense out the disfigured decompiled code to understand how some internal stuff works.
If the source code was made available(and protected with appropriate licensing) would be a great valuable help to all plugin developers. Even greater than good documentation. After all, code is also documentation.

0

Let me make a suggestion (again): Have a wiki for javadoc - should be automated, so that
user edited content gets promoted to real javadoc in the next release, or maybe just
integrated into Idea's own javadoc viewer.


+10. This is a fantastic idea.

Also it would help a lot if the standard plugins that
already come with source would also
include an Idea project that you can simply open and
start browsing source code


+1.

0

Hello Stephen,

Let me make a suggestion (again): Have a wiki for javadoc - should be automated,

so that

user edited content gets promoted to real javadoc in the next release,
or maybe just integrated into Idea's own javadoc viewer.


How about we start with existing infrastructure - JIRA and patches? If you
are willing to contribute javadocs, just write them, create a patch and attach
it to a JIRA request. We'll review them and apply the patch if it's OK.

Of course a dedicated "collaborative javadoc writing" environment can make
this more seamless and effortless, but it would be rather wasteful to spend
a lot of time creating the environment and then to find no one using it.

Also we can create a Confluence space on jetbrains.net where people could
write notes on our OpenAPI. We had this once on intellij.org, but it didn't
seem to work too well.

One thing that I personally consider very helpful and fairly easy to create
is a "topical forum index" - references to threads in OpenAPI forum grouped
by functional area. Would anyone be interested in creating and maintaining
such an index?

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"


0

I think one of the reasons for the this is the lack of proper documentation (beside javadoc).

Alexander,

This problem was discussed allot in the last years, and many ideas were provided by the community,
but there's still no better docs.
The thing that is really missing is that Jetbrains employees "just do it".

If you look at the Jetbrains WIKI:
http://www.jetbrains.net/confluence/dashboard.action
you will see how good TeamCity is documented and how often the docs get updated, so basically it's a
matter of "just doing it". From the usernames one can see that there are not just one employee ,but
more that work on those docs almost every day.

Now how about allocating a team of writers to IntelliJ too?

IMHO this is a problem of mismanagement, as the IntelliJ developers are doing the impossible,
(even support on these forums), and this since years.

Ahmed.

0

Hello Ahmed,

This problem was discussed allot in the last years, and many ideas
were provided by the community,
but there's still no better docs.
The thing that is really missing is that Jetbrains employees "just do it".
If you look at the Jetbrains WIKI:

http://www.jetbrains.net/confluence/dashboard.action

you will see how good TeamCity is documented and how often the docs
get updated, so basically it's a

matter of "just doing it". From the usernames one can see that there
are not just one employee ,but
more that work on those docs almost every day.

Now how about allocating a team of writers to IntelliJ too?

IMHO this is a problem of mismanagement, as the IntelliJ developers
are doing the impossible, (even support on these forums), and this
since years.


For what it's worth, TeamCity has only one dedicated writer. The many employees
you see updating the docs are TeamCity developers.

IDEA does have several dedicated writers, but they are working on end-user
content (help system, demos, blog posts etc.) rather than plugin development
documentation.

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"


0

IDEA does have several dedicated writers, but they are working on
end-user content (help system, demos, blog posts etc.) rather than
plugin development documentation.


Is this a fixed state?

0

Hello Tom,

>> IDEA does have several dedicated writers, but they are working on
>> end-user content (help system, demos, blog posts etc.) rather than
>> plugin development documentation.
>>

Is this a fixed state?


From the information I have, I don't see much chance of this changing before
the 7.0 release.

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"


0

For what it's worth, TeamCity has only one dedicated writer. The many
employees you see updating the docs are TeamCity developers.

IDEA does have several dedicated writers, but they are working on
end-user content (help system, demos, blog posts etc.) rather than
plugin development documentation.

Well, than my mistake.
However, from a "customer" point of view (the impression), TC is moving forward (constantly), but
IntelliJ does not (in this context).

Also, I'm convinced the "end-user" content is very important for any IDE, but you must not forget
your target users - they are programmers - they' don't need precise and detailed description how to
select and click in the IDE, but advanced items, and plug-in writting goes into this category much
more IMHO.

Ahmed.

0

How about we start with existing infrastructure -
JIRA and patches? If you
are willing to contribute javadocs, just write them,
create a patch and attach
it to a JIRA request. We'll review them and apply the
patch if it's OK.


That would be easier if it were possible to create patches from local history: http://www.jetbrains.net/jira/browse/IDEADEV-14303
Hint hint:-)

Bas

0

Hi Dmitry,

the lack of documentation is a serious problem for us plug-in developers. I think that many of us wasted a lot of time because there is no text in the javadoc of many classes. Often it is difficult to find out how a API should be used. Then we have to try and try and try...

While I understand that it is a larger task to fully document the API, I really do not understand that newly added classes/interfaces/methods do mostly have no javadoc. You know, when implementing a new class or method it takes only a few minutes more to add javadoc.

I'm also missing the @since 7.0 tags. There is not a single one in build 6951.

IMHO the IDEA project lead should encourage (or should I say "force") the IDEA developers to add javadoc and @since tags at least to newly created classes/interfaces/methods.

Karl

0

I must say I disagree.

Adding full JavaDoc to the complete API will be a huge effort, and the benefits
questionable.
Adding "@return FooBar implementation" takes no time, writing meaningful,
high-quality comments is hard work in my experience.
Of course it's good to have documentation, but majority of external plugins
use a few core APIs.
Besides, JavaDoc is not the best place for detailed explanations.

I think a good way forward would be to:
1) More JavaDoc, but on essential, stable parts of API only
2) Perhaps make implementation source available for parts where it makes
sense
3) Core concepts deserve some prose in the style of "IntelliJ IDEA 6.0 Architectural
Overview":
http://www.jetbrains.net/confluence/display/IDEADEV/IntelliJIDEA6.0ArchitecturalOverview
4) Topical index (idea Dmitry)

For (1), (2) and (3), how should Jetbrains know which API areas are "most
wanted"?

-tt


0

Dmitry Jemerov wrote:

Of course a dedicated "collaborative javadoc writing" environment can
make this more seamless and effortless, but it would be rather wasteful
to spend a lot of time creating the environment and then to find no one
using it.


I agree, but otoh this may the same difference as between nupedia and wikipedia.

How about uploading the OpenAPI docs to JDocs and writing an Idea plugin that makes
showing and editing comments at JDocs easy (e.g. ctrl-q automatically also shows user
comments from JDocs plus a button to add a comment).
I tried to search to check whether maybe the openapi is already there, but the result
only shows how very valuable the "default template usage" inspection is:
http://www.jdocs.com/search.jsp?s=intellij

Also I found that there is indeed a collaborative-javadoc-wiki-thingy in work:
https://www.inf.fu-berlin.de/w/SE/ThesisWikiDoc
(Starts in German, but the rest is in English.)
It's an ongoing thesis, so it's hard to say how usable the result will be.

0

The point of my post is that JetBrains still creates new API without javadoc, although the missing API javadoc is a long known problem. So the problem is getting bigger and bigger...

With not much time it should be possible to add javadoc to just added API. The developer knows what the just created class is good for and what a new method does.

On the other hand, writing the javadoc one year later is much harder and more time consuming. The developer has to read the code again and find out the details...

Karl

0

On the other hand, writing the javadoc one year later is much
harder and more time consuming. The developer has to read the
code again and find out the details...

If this is for the Jetbrains developer heavy (that has the source code in front),
how heavy is that for plug-in developers :).

One must be really a masochist to develop plug-ins under these conditions :). This also the reason
not to many big companies jumped on Jetbrains plug-in development wagon, but only individuals.

Ahmed.

0

I'll echo what others have said. In-IDE Javadoc wiki would be great and I would happily contribute to it. More documentation would probably save me hours and hours per week and probably allow me to use API's I don't even try using currently. Closed-source but publically available source code would be immeasurably valuable.

0

I was just going to ask, how one is supposed to create patches w/o first creating and maintaining a VCS containing OpenAPI :)

0

The complaint and the response are both valid. The addition of the general FAQ is helpful but incomplete. Would you be willing to publish the existing documentation as a wiki? I know I've learned a couple things developing a custom language API, and I think if we just had a very few people updating the wiki with what they've learned, it would provide tremendous value to the community - and to the product - with minimal cost to JetBrains.

How about it?

0

Hello Kurt,

The complaint and the response are both valid. The addition of the
general FAQ is helpful but incomplete. Would you be willing to publish
the existing documentation as a wiki? I know I've learned a couple
things developing a custom language API, and I think if we just had a
very few people updating the wiki with what they've learned, it would
provide tremendous value to the community - and to the product - with
minimal cost to JetBrains.

How about it?


The new documentation is already written on our Wiki:
http://www.jetbrains.net/confluence/display/IDEADEV/Home (Plugin Development
section)
If anyone would like to get write access for modifying the documentation,
we can arrange that.

The "Custom languages" article will also likely migrate to Confluence when
I'll find the time to update it for version 8.

For Javadoc documentation, I'm still not aware of any good collaborative
editing solution, but, as I've said before, we're happy to accept patches
for our OpenAPI javadocs.

--
Dmitry Jemerov
Development Lead
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"


0

Please sign in to leave a comment.