Hey Jens,
On Feb 12, 2010, at 1:05 PM, Jens Hübel wrote:
Hi Gabriele,
thanks for this fast feedback. Actually we started with maven site
but transferred our stuff to Confluence. The mvn site seems not to
be very convenient for larger documentation work. Each typo fix
needs a complete recompilation for seeing what you have written. You
also need svn access for fixes. Confluence offers more comfort and
better tooling imho. Personally I would appreciate if the barrier to
provide useful documentation is not too high.
Not sure what your past experiences are with Maven sites (probably not
that positive :))),
but I've been building apps with Maven and documenting them for quite
a while now and I don't think there's a better way to keep docs inline
with code and properly versioned.
I have experienced exactly the opposite for documentation:
- wiki does not scale properly to larger documentations because you
easily get lost and it's *very* unstructured. It's also difficult to
have a 1-1 relationship between modules and docs, while this is
basically enforced by the mvn site structure
- about your concerns in the development process:
- mvn site:run [1] will just run an embedded jetty which is serving
the documentation site for the module you're working on, and take
changes on the fly (so that you can write and refresh) so you don't
need recompilation
- full builds are required only to check proper linking between modules
- also APT (if that the format you use) has an Eclipse plugin [2]
which allows you to preview the resulting visual without even invoking
mvn
- about svn, I'm actually VERY HAPPY that docs are checked in (in a
textual format, not the nasty PDFs or DOCs) in SVN inline with the
code. I believe this is the whole purpose of the mvn site features and
allow people not to get lost between different versions of
documentation (wiki is basically flat unless you manage versioning
manually)
- the TCK(s) are run as JUnits, and using the mvn sites might allow
to produce a maven report on the different server implementations
levels of compatibility to the standards
Are there any guidelines how Apache projects use these tools and
what belongs where? Are there any plans how the others want to make
use of it?
Said that, apart from the links already circulated on the thread, my
vision here is:
- Marketing / Howtos / 5 minutes intro / simple pointers / design
docs / use cases / proposals ---> should happily go in the wiki
- Developer docs / project reports / API docs / structured per module
docs --> mvn site
A longer term plan (and more risky) might instead take into account to
use the maven site engine (Doxia) to bridge these two worlds. Doxia
1.1 infact includes :
1. A confluence source module (meaning that you can write confluence
pages and then use them as input for a mvn site generation)
2. A confluence sink module (which means that you can write standand
mvn docs and then generate markup which can be deployed on Confluence)
My 0.02€ say to consolidate on Maven because of the number of reports
and OOTB features it offers. But I'm eager to hear what do the other
guys think, as this is a non trivial decision.
HTH,
ciao!
Gab
[1] http://maven.apache.org/plugins/maven-site-plugin/examples/siterun.html
[2] http://apteditor.sourceforge.net/
[3]
http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-confluence/index.html
[4]
http://jira.codehaus.org/browse/DOXIA-124?page=com.atlassian.streams.streams-jira-plugin%3Aactivity-stream-issue-tab
Thanks Jens
-----Original Message-----
From: Gabriele Columbro [mailto:colum...@gmail.com]
Sent: Freitag, 12. Februar 2010 09:48
To: chemistry-dev@incubator.apache.org
Subject: Re: Chemistry documentation page
Hi Jens,
I see the wiki actually as more developers/design documentation while
I see the comprehensive and structured documentation as perfect fit
for the Maven site capabilities.
That would automatically generate a default documentation site (with
selected reports) per every module + every custom documentation page
you write in the src/site folder of that module.
What do also the others think?
Ciao!
Gab
On Feb 12, 2010, at 8:50 AM, Jens Hübel wrote:
Hi,
we have started putting some documentation about OpenCMIS in the
Confluence wiki (http://cwiki.apache.org/CMIS/opencmis.html). With
the increasing community and the recent contributions the Chemistry
structure gets more complex. I think we need an overview page and
sub-sections for the sub projects. We also should provide a
description how the sub projects depend on each other or where they
are independent.
Are there any proposals out there how to design the project
navigation?
Jens
--
Eng. Gabriele Columbro
Alfresco Software, Ltd.
M: +31 (0)627 565 103
P: +39 320 161 28 46
D: +44 (0)1628 876 654
Skype: gabrielecolumbro
Blog: http://www.mindthegab.com
--
Eng. Gabriele Columbro
Alfresco Software, Ltd.
M: +31 (0)627 565 103
P: +39 320 161 28 46
D: +44 (0)1628 876 654
Skype: gabrielecolumbro
Blog: http://www.mindthegab.com
