RFC: Wiki + JavaDoc

[=?iso-8859-1?q?Christopher_=D6zbek?=]

Hello Java-Friends,
I would like to ask for your feedback on an idea for an JavaDoc
enhancement:

Imagine that you could edit each JavaDoc comment on a JavaDoc site like
http://java.sun.com/j2se/1.4.2/docs/api/ using the wiki command "edit".
Changes that you make to the comment get directly reflected both on the
html page and in the underlying source-code.

With a Wiki you get the following advantages:
- Open for user collaboration
- Version control to rollback to better versions (for instance
because of vandalism)
- Proven, known and popular interface (just think of
www.wikipedia.org).

Reflecting the changes from the JavaDoc page back into the source-code
has the following advantages:
- Contributing to your favorite APIs is now much easier.
- Users can be asked to collaborate:
- For instance after a user asked a question on a mailing-list it's
now possible to ask the person to contribute the solution s/he got on
the mailing-list to the documentation.

Of course there are also disadvantages:
- It could be difficult to accumulate enough users to reach critical
mass.
- The quality of the documentation could be rather bad.

Implementation should be not to difficult as both JavaDoc and Wikis are
well established technologies.

Please let me know whether you think this is feasible and useful.

Can you imagine using such a system?

Would you mind if your own API was using the system and users would
change comments you have written?

You can find a mockup-walk-through at:

http://page.mi.fu-berlin.de/~oezbek/cgi-bin/view/Docu/WikiDoc#Mockup_Walkthrough

....and a use case for an Open Source project at:

http://page.mi.fu-berlin.de/~oezbek/cgi-bin/view/Docu/WikiDoc#Use_Scenario_1_F_OSS_Project

Thanks you for your comments,
Christopher

 

[Rhino]

Hello Java-Friends,
I would like to ask for your feedback on an idea for an JavaDoc
enhancement:

Imagine that you could edit each JavaDoc comment on a JavaDoc site like
http://java.sun.com/j2se/1.4.2/docs/api/ using the wiki command "edit".
Changes that you make to the comment get directly reflected both on the
html page and in the underlying source-code.

With a Wiki you get the following advantages:
- Open for user collaboration
- Version control to rollback to better versions (for instance
because of vandalism)
- Proven, known and popular interface (just think of
www.wikipedia.org).

Reflecting the changes from the JavaDoc page back into the source-code
has the following advantages:
- Contributing to your favorite APIs is now much easier.
- Users can be asked to collaborate:
- For instance after a user asked a question on a mailing-list it's
now possible to ask the person to contribute the solution s/he got on
the mailing-list to the documentation.

Of course there are also disadvantages:
- It could be difficult to accumulate enough users to reach critical
mass.
- The quality of the documentation could be rather bad.

Implementation should be not to difficult as both JavaDoc and Wikis are
well established technologies.

Please let me know whether you think this is feasible and useful.

Can you imagine using such a system?

Would you mind if your own API was using the system and users would
change comments you have written?

You can find a mockup-walk-through at:

http://page.mi.fu-berlin.de/~oezbek/cgi-bin/view/Docu/WikiDoc#Mockup_Walkthrough

...and a use case for an Open Source project at:

http://page.mi.fu-berlin.de/~oezbek/cgi-bin/view/Docu/WikiDoc#Use_Scenario_1_F_OSS_Project

This is an interesting idea. I can see a use for it as a way to add
documentation to classes and methods where the existing documentation is
sparse or even non-existent. I'm sure we've all seen classes and methods,
even in the standard Java API, where it was not at all obvious what they
were or how to use them. If developers who have used them and come to an
understanding want to add that knowledge to the existing Javadocs, it would
seem to be a very positive thing.

On the other hand, I see some problems.

First, how do you ensure accuracy? A user may *think* they understand a
particular class or method and write documentation that reflects that
understanding but what if they are wrong? What if they have misunderstood
it, either slightly or significantly, and write documentation that is
therefore false or misleading? This may be more harmful than leaving the
documentation alone. After all, if the documentation says nothing at all, a
user may bypass the class or method altogether rather than trying to guess
what it does. If the documentation says that the code does A when it
actually does B, the developer wanting to do A may try it and get frustrated
when it actually does B, especially if B is destructive in some way.

Furthermore, what happens if different Good Samaritans come along and each
contribute different, *conflicting* documentation? Now the number of
possible meanings of the code multiply. There might be three conflicting
sets of documentation added to the class and ALL of them might be wrong.

Frankly, I suspect most people will agree that only the person or people who
actually developed the class are the appropriate ones to document it; they
know what problem they were trying to solve and how they went about solving
the problem. If they failed to document it or didn't do a very clear job of
it, that is everyone's loss but it might be better to lobby the developers
to improve their documentation than to guess what documentation should be
there and write it yourself for fear of being wrong.

I'm also curious how you plan to reintegrate the Javadoc changes back to the
source code. Do you plan to obtain copies of the source code for every Java
API in existence? How do you plan to keep that source code current since it
might change at any time? What scope are you envisioning for this
initiative: just the standard java/javax classes or all the other Java APIs
that are in existence?

I'm doubtful that most companies will give you their source code for a
variety of reasons:
- fear of giving away secrets
- fear of you introducing errors into the source code in the form of bad
javadoc tags
- not wanting to be bothered with verifying/implementing the Javadoc changes
- etc.

Assuming I'm right about that, you might have to keep a parallel set of
Javadocs, a set that is parallel to the "real" Javadocs but not vetted by
the developers of the code and not integrated into that code. That strikes
me as very problematic. At the very least, there would be confusion about
which set of Javadocs was the "real" set and which was the "enhanced but
unvetted" set.

In my view, it would make more sense to redesign this idea somewhat. Use
this idea to accumulate suggestions for improvements to Javadocs with the
intention of having the developer (eventually) verify that the accumulated
changes are accurate and then integrate them into the source code so that
new Javadocs can be generated from the source. That would let the developers
of these classes take advantage of the effort made by people to document
their classes but to do it on their own schedule and without giving away any
secrets.

I think a lot of good could come from this initiative but only if proposed
changes to the documentation are clearly understood to be proposals that
have not yet been vetted by the developer. Once the developer has verified
that the changed documentation is better and adds them to the source code,
new Javadocs can be issued. Then the cycle can begin again as users make
further improvements.

Rhino

 

[=?iso-8859-1?q?Christopher_=D6zbek?=]

This is an interesting idea. I can see a use for it as a way to add
documentation to classes and methods where the existing documentation is
sparse or even non-existent. I'm sure we've all seen classes and methods,
even in the standard Java API, where it was not at all obvious what they
were or how to use them. If developers who have used them and come to an
understanding want to add that knowledge to the existing Javadocs, it would
seem to be a very positive thing.

Unfortunately the standard Java API would have to be excluded from
this, since it is not available openly as source.

On the other hand, I see some problems.

"accuracy", "wrong behavior by users", "conflicting docu"

There are two ideas for this:

1.) Wikipedia manages to produce good articles why shouldn't it work
for editing JavaDocs? In general wiki managed projects with a fair
amount of users are usually maintained very orderly.

2.) How about an extension of the Wiki idea: Keep an authoritative
version of the documentation. That way you can display a little red
exclamation mark that tells people: "This version is not official,
click here to see the what is in the authoritative copy"? Do you think
this could work?

Frankly, I suspect most people will agree that only the person or people who
actually developed the class are the appropriate ones to document it;

Exactely! But they have so much work that it might be better if
somebody else does the job and they just read over it to make sure it
is done right. This would interface nicely with the authoritative
version, because you can give all project members "commit"-privileges.
They can then approve changes or roll them back.

I'm also curious how you plan to reintegrate the Javadoc changes back to the
source code.

I had a look around for implementation possibilities and the most
promising approach would be to use the parser from the Eclipse
platform. In contrast to the doclet API from Sun the Eclipse parser has
the capabilities to locate and replace code elements (for instance the
comments). Alternatively it is possible since Java 1.4 to get the
source code position (unfortunately not as a range, but just a pair of
line and column) and then put some regular expressions for replacing
the comment to work.

Alternatively there is XDoclet which is capable of transforming the
source, too. Unfortunately XDoclet does not seem to make progress
towards Java 1.5, last time I checked.

There are more possiblities like ANTLR on the idea page (link at the
end of the mail).

Do you plan to obtain copies of the source code for every Java
API in existence?

An idea would be rather to write a servlet that each project could just
drop into a Tomcat, tell the servlet the address of the project CVS and
the rest would be done automatically. Any body wants to comment on the
feasibility of this?

At the very least, there would be confusion about
which set of Javadocs was the "real" set and which was the "enhanced but
unvetted" set.

mh. That would need some investigation with more developers. Any
opinions anybody else?

Thanks very much for your comments Rhino!

Have a look at the wiki pages I have set-up for the purpose of
discussing the idea:

http://page.mi.fu-berlin.de/~oezbek/cgi-bin/view/Docu/WikiDoc

Christopher