portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Shah Amit" <amit_sha...@hotmail.com>
Subject RE: Jetspeed 2 M4 focus: Documentation !
Date Fri, 03 Jun 2005 13:11:21 GMT
Hi all,

I am no expert on this one so please disregard if you find my comments 
ridiculous !!! But regarding suggestion #4, I have a suggestion !!!!

I know that usually opensource projects lack in documentation and I can 
understand why. Lot of times, the documentation that is there is in form of 
random bits and pieces, and there is no "flow" saying learn this first, then 
learn this second, then learn this third etc. etc. Due to this atleast I 
have faced problems jumping back and forth around the documentation.

If there is a documentation that kind of flows --

Just one link that says Documentation and then like a chapter 1, chapter 2 
etc. it would really be sweet !!!

Thanks,
Amit

----Original Message Follows----
From: RaphaŽl Luta <raphael@apache.org>
Reply-To: "Jetspeed Developers List" <jetspeed-dev@portals.apache.org>
To: jetspeed-dev@portals.apache.org
Subject: Jetspeed 2 M4 focus: Documentation !
Date: Fri, 03 Jun 2005 11:24:13 +0200

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