As you can see at http://cocoon.zones.apache.org/dev-docs/ I was working on our
documentatation again, in particular on
o the homepage
o main site documents
o getting started guides
o Maven reporting
Homepage
Except that the Versions headline is shown twice, it already has the structure
that I intend.
It also contains the defintions of Apache Cocoon and Cocoon blocks.
Feedback on the structure and the definitions would be highly appreciated. It
would also be very helpful if native speakers could proofread the definitions.
Main Site
-
Like the homepage, IMO the structure of the main site is completed too. Some of
the ideas are borrowed from some well-known scripting framework for web
applications. The content still needs some work but I hope that I find some time
next week.
Again, feedback7work on the structure/content and the help from native speakers
would be very helpful.
Getting started guides
--
So far I wrote three tutorials:
- Your first Cocoon application using Maven 2
(http://cocoon.zones.apache.org/dev-docs/1159_1_1.html)
- Usage of the reloading classloader [1]
- Debugging Cocoon in Eclipse
http://cocoon.zones.apache.org/dev-docs/1301_1_1.html
It would be very helpful if you can go through the three reports and verify if
everything works as described. Proof-reading from native speakers would be
helpful again.
Reporting
-
One of the big advantages of Maven is that it makes the report generation very
simple as the inclusing into the docs is done completly declarative.
I separated the possible reports into several profiles:
o default reports
These are the reports which will be added to our official documentation at
http://cocoon.apache.org. IMO these are the
- Project information (dependencies, license, summary, team)
- Javadocs
- Changes
If the sub-documentation site doesn't have any docs in Daisy (e.g.
the Cocoon Pipeline API[2] also the About report is added which
creates an index.html file taking its information from the
description element of the POM.
o all-reports
These are the reports that contain useful information for developers and
people who want to get familiar with our codebase but it's simply too
much to put them all into our official website (and into SVN).
You can find following reports
- FindBugs (FindBugs™ is a program to find bugs in Java programs. It looks
for instances of bug patterns --- code instances that are likely to be
errors.)
- JDepend (JDepend traverses Java class file directories and generates
design quality metrics for each Java package. JDepend allows you to
automatically measure the quality of a design in terms of its
extensibility, reusability, and maintainability to manage package
dependencies effectively.)
- dev-activity (who has changed which files within the last 30 days)
- file-activity (which files were changed within the last 30 days)
- Source XRef (HTML based, cross-reference version of Java source code.)
- Tag List (Report on various tags found in the code.)
at http://cocoon.zones.apache.org/dev-docs-all-reports/.
o testing-reports
Here you can find the Junit and the Cobertura (test coverage) reports.
Both don't work ATM because our unit tests don't run through at the
moment. As soon as they are fixed, I will move them into the all-reports
profile.
o simian-report
The simian report shows valuable information about duplicated code.
For some reasons the Maven plugin isn't available
at the public Codehaus Maven repository. I guess this was caused by
the hardware problems at Codehaus last year and the plugin snapshot
hasn't been rebuilt yet.
In order to invoke the Simian report, you have to install the jars
manually into the local Maven repoistory. I did this for the local
repo of our Maven user at our zone which is used to run Continuum.
There is also an interesting reporting plugin called JDiff
(http://mojo.codehaus.org/jdiff-maven-plugin/) which provides information about
the differences between two versions of an API. Find a sample report at
http://mojo.codehaus.org/jdiff-maven-plugin/changes.html. As soon as we have
released stable versions of our modules, I will add the plugin to our
all-reports profile and we will benefit from a good overview of what we have
changed.
- o -
As I'm coming to the end of my mail, here my usual request: For those who are
interested in writing documentation, find information about it at
http://cocoon.zones.apache.org/daisy/cdocs/1201.html. If you just want to edit a
document, follow the links at the bottom of the generated docs, log in into
Daisy and edit the page. Help would be really, really appreciated and would
speed up things a lot!
- o -
I
