Re: [Java-gnome-developer] Enforcing documentation quality

[Andrew C. <an...@op...>]

On Tue, 2011-01-18 at 20:52 -0500, Nick Khamis wrote:
> We have been working on a project called the JavadocMiner that
> evaluates the quality of Javadoc comments. Included in our list of
> metrics are the readability
> measures

Sounds interesting.

In the java-gnome project we have a fairly deliberate documentation
style that is somewhat different from the (in my humble opinion) poor
norms that tend to exist in most Java libraries.

That's a human judgement, but of course it'd be interesting to see what
your algorithms have to say about it.
http://java-gnome.sourceforge.net/4.0/doc/style/Documentation.html and
http://java-gnome.sourceforge.net/4.0/doc/design/2b-DesignConstraints.html#hand-written
discuss our approach (and the requirements necessary before we accept
patches to 'mainline').

> If you would like to use the tool to analyze the different
> applications of your project
> we would be happy to open source it for you.

Um, sure?

Choosing to publish a piece of software under an Open Source licence is
a decision for you the authors and/or your supporting organizations, but
(speaking with my corporate hat on for a minute) we'd certainly welcome
you joining the vast community of people and organizations who make
their work available!

For what it's worth, I'd encourage you to pick a GPL compatible licence
(ie, GPL, or BSD, or... not Apache etc). If you do that from the outset
then it prevents all kinds of confusion later. But that's up to you.

AfC
Sydney

-- 
Andrew Frederick Cowie

Operational Dynamics is an operations and engineering consultancy
focusing on IT strategy, organizational architecture, systems
review, and effective procedures for change management: enabling
successful deployment of mission critical information technology in
enterprises, worldwide.

http://www.operationaldynamics.com/

Sydney   New York   Toronto   London