cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Current status of the new documentation
Date Sat, 06 Jan 2007 14:14:08 GMT

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 will continue to work on the docs, in particular I will complete the main-site 
docs and provide minimal information about all core modules (e.g. see [2]) and 
blocks. I expect that this will take me one week or two. Then we are ready to 
publish them together with the planned next release of cocoon-core-2.2-M3 
release series at the end of the month, IMO.


[1] 
http://cocoon.zones.apache.org/dev-docs/maven-plugins/reloading-classloader-plugin/1.0/1297_1_1.html
[2] 
http://cocoon.zones.apache.org/dev-docs/core-modules/pipeline-api/1.0/project-info.html


-- 
Reinhard Pötz           Independent Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------

Mime
View raw message