portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Scott T Weaver" <scotts-jetspeed-l...@binary-designs.net>
Subject RE: Jetspeed 2 M4 focus: Documentation !
Date Fri, 03 Jun 2005 13:08:13 GMT
Raphaël,

I started component docs here,
http://wiki.apache.org/portals/Jetspeed2/PluggableEngineComponents, sometime
ago.  Unfortunately, they are quite out of date :(

I agree 110% the documentation should be our focus now.  I don't think any
of us will disagree that it is severely lacking.  However, I know Randy
Watler has provided some excellent high-level docs on the refactoring of
navigation.

Regards,
Scott


> -----Original Message-----
> From: Raphaël Luta [mailto:raphael@apache.org]
> Sent: Friday, June 03, 2005 5:24 AM
> To: jetspeed-dev@portals.apache.org
> Subject: Jetspeed 2 M4 focus: Documentation !
> 
> 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



---------------------------------------------------------------------
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