portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Raphaël Luta <raph...@apache.org>
Subject Jetspeed 2 M4 focus: Documentation !
Date Fri, 03 Jun 2005 09:24:13 GMT
What:
-----
I'd like to propose a specific focus sor the upcoming M4 release: improving the 
documentation available on jetspeed 2 and possibly reorganise the repository to
make it easier for new developpers (or returning developpers like me :) to get
into the code.

Why:
----
- Every time I talk of J2 to external developers (integrators, and such...) 
complexity and lack of documentation is the top 1 grief when they have looked
at using J2.
- I'm developping a new feature right now (PagePreference) and I'm losing a
*ridiculous* amount of time trying to understand how the stuff is organized
and how everything interacts:
   - many classes have no javadocs explaining what this class is about
   - the java package structure is seemingly unrelated to the "physical"
     packaging, so it's basically just looking at a class name to know where
     it's located (jetspeed-api, commons, components, demo, etc..), against
     losing way too much energy trying to navigate.
   - the Spring assembly conf files are (mostly) undocumented

If I'm feeling such a pain, I can really sympathize with an external portal 
integrator developers building on top of J2 and trying to get some results
fast.

How:
----
Providing there's approval within the community for this drive, I propose that
we tackle it in this order :

#1 Move to SVN.
   This will make any refactoring/repackaging much easier.

#2 Start a thread on how to manage our java packages and adopt a clear package
   naming policy for the different main code blocks:
   - jetspeed-api
   - jetspeed engine core components
   - jetspeed engine optional components
   - application level code (admin stuff, portlet stuff, etc...)
   - generic utility code

#3 Update Javadocs and assembly files as soon as possibly :
   - if possible go through all the different classes and document them at least
     at a basic level of details
   - at the very least, whenever working on a class make sure to comment this
     class before committing

#4 Rework the user documentation and developer design docs or HOWTO
    Update and reorganize the existing design-docs, move to forrest

Task #1 is underway
Task #2 should be approached as a group and I think will be pretty easy to so 
thaks to IDE power.
Task #3 really requires the active collaboration of everybody knowledgeable with
the code
I volunteer to drive #4 and complete the forrest site I've started.

-- 
Raphaël Luta - raphael@apache.org
Apache Portals - Enterprise Portal in Java
http://portals.apache.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message