You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Reinhard Poetz <re...@apache.org> on 2007/01/06 15:14:08 UTC
Current status of the new documentation
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
--------------------------------------------------------------------
Re: Current status of the new documentation
Posted by Jeremy Quinn <je...@apache.org>.
On 6 Jan 2007, at 20:22, hepabolu wrote:
> Jeremy Quinn said the following on 6/1/07 20:22:
>>>> OK, I only have 'guest' under the role menu, so I assume someone
>>>> has to enable me as a doc-editor?
>
> Fixed. Your default role is doc-editor, but I've also given you the
> doc-committer role (since you're a committer ;-) ) which is allowed
> to put documents live.
Thanks Helma
( oh ****! now I have to do something :-) )
regards Jeremy
Re: Current status of the new documentation
Posted by hepabolu <he...@gmail.com>.
Jeremy Quinn said the following on 6/1/07 20:22:
>>> OK, I only have 'guest' under the role menu, so I assume someone has
>>> to enable me as a doc-editor?
Fixed. Your default role is doc-editor, but I've also given you the
doc-committer role (since you're a committer ;-) ) which is allowed to
put documents live.
HTH.
Bye, Helma
Re: Current status of the new documentation
Posted by Jeremy Quinn <je...@apache.org>.
On 6 Jan 2007, at 17:29, Mark Lundquist wrote:
>
> On Jan 6, 2007, at 9:13 AM, Jeremy Quinn wrote:
>
>> OK, I only have 'guest' under the role menu, so I assume someone
>> has to enable me as a doc-editor?
>
> Reinhard can do that if need be, but first... are you logged in as
> your real self? What does it say on the "User: " menu, and is
> there a "Change login" item under it?
Yes :)
regards Jeremy
Re: Current status of the new documentation
Posted by Mark Lundquist <ml...@wrinkledog.com>.
On Jan 6, 2007, at 9:13 AM, Jeremy Quinn wrote:
> OK, I only have 'guest' under the role menu, so I assume someone has
> to enable me as a doc-editor?
Reinhard can do that if need be, but first... are you logged in as your
real self? What does it say on the "User: " menu, and is there a
"Change login" item under it?
—ml—
Re: Current status of the new documentation
Posted by Jeremy Quinn <je...@apache.org>.
Hi Mark
Thanks for the reply.
On 6 Jan 2007, at 17:04, Mark Lundquist wrote:
>
> On Jan 6, 2007, at 8:53 AM, Jeremy Quinn wrote:
>
>> I found a few spelling mistakes and registered for an account to
>> edit the document.
>> Forgive me if I am being dumb, but where is the edit link?
>> Do I need to be upgraded from role:guest ?
>
> You have to use the "Role:" pulldown menu to manually change roles
> to "doc-editors". Then the "edit" item will appear under the "Page
> Actions" pulldown menu.
OK, I only have 'guest' under the role menu, so I assume someone has
to enable me as a doc-editor?
thanks
regards Jeremy
Re: Current status of the new documentation
Posted by Mark Lundquist <ml...@wrinkledog.com>.
On Jan 6, 2007, at 8:53 AM, Jeremy Quinn wrote:
> I found a few spelling mistakes and registered for an account to edit
> the document.
> Forgive me if I am being dumb, but where is the edit link?
> Do I need to be upgraded from role:guest ?
You have to use the "Role:" pulldown menu to manually change roles to
"doc-editors". Then the "edit" item will appear under the "Page
Actions" pulldown menu.
cheers,
—ml—
Re: Current status of the new documentation
Posted by Jeremy Quinn <je...@apache.org>.
Excellent start Reinhard
On 6 Jan 2007, at 14:14, Reinhard Poetz wrote:
> 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.
I found a few spelling mistakes and registered for an account to edit
the document.
Forgive me if I am being dumb, but where is the edit link?
Do I need to be upgraded from role:guest ?
thanks
regards Jeremy