incubator-chemistry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jens Hübel <jhue...@opentext.com>
Subject RE: Chemistry documentation page
Date Fri, 12 Feb 2010 13:28:10 GMT
Ah interesting information. I did not know about the dynamic refresh feature of a mvn run in
parallel to editing. I will try this. I had a look at the Eclipse plugin for APT, but found
this quite limited. Thanks for the update!

Jens


-----Original Message-----
From: Gabriele Columbro [mailto:columbro@gmail.com] 
Sent: Freitag, 12. Februar 2010 13:30
To: chemistry-dev@incubator.apache.org
Subject: Re: Chemistry documentation page

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:columbro@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



Mime
View raw message