cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Date Mon, 24 Mar 2003 15:09:35 GMT
Steven Noels wrote:
> On 24/03/2003 14:23 Stefano Mazzocchi wrote:
> 
>> I don't expect 2.0 to live long after 2.1 is out. There is no reason to.
> 
> 
> To be really honest, I'd like to see some facts backing this statement. 
> Not technical facts, but truly compelling reasons to make the switch. If 
> people don't go with the flow, or with xmlform, why should there be a 
> reason to switch?

Tons of it:

1) modularity: you can include in your cocoon, only what you really 
need, keeping memory lower and lowering the chance of bugs and potential 
security holes

2) interpreted sitemap: reduces your try fail cycle

3) tunable pipelines: you can have caching/non-caching granularity

4) better proxy friendlyness: improves your speed for static resources.

These are the most evident but there are tons of them if you look at 
changes.xml.

Anyway, we can't force people to do anything: if they won't migrate from 
2.0, we have failed and we should start reconsidering our architectural 
strategies because our user base is not following us.

Still, given the feedback i received on 2.1, I don't think this will 
happen, as it didn't happen between cocoon 1.x and 2.x even if the 
changes were so radical.

The 2.0 -> 2.1 transition will be piece of cake compared to that, trust me.

>> If there is something back-incompatible, it's a bug and it will be 
>> fixed. Nobody should have problems in switching to 2.1 and if they 
>> did, we fix their problems because we (and them) *expect* an easy 
>> migration.
>>
>> At that point, there will be only *one* repository for docs and it 
>> will live close to the code it belongs to.
> 
> 
> Sigh. I don't understand, and perhaps will never understand, what this 
> obsession is with keeping docs close to code.

There is no 'obsession', Steven. I'm wide open to arguments that tell me 
why keeping the docs with the code is wrong.

Diana's arguments about duplication of effort are good ones, but I 
pointed out that they are only short-term ones until the transition is 
finished and should not influence our longer-term vision.

> I see three types of documentation involved in a generic software project:
> 
>  * code-based documentation, aka Javadocs & comments
>  * reference documentation, which could possibly be partly generated out 
> of the above, and states the exact input/output requirements and 
> behavior of components

Javadocs has one huge drawback: they aren't semantic. If we had semantic 
javadocs, we could integrate more meaningful javadocs into our own 
documentation and this would be *so* nicer than what we have today.

javadocs are cool and useful, but they are too developer oriented. 
Still, if we had semantic capabilities, we could write skins to make it 
more 'forrest-friendly' for example, and provide more coherent visual 
semantics. Worth thinking for forrest, IMO.

>  * 'user' documentation, like 'building new Cocoon components', or 
> 'installing Cocoon on Znorbaf appserver'

I agree the first two are somewhat different from the last one.

> I agree blocks & modular builds kinda spoil my picture, but the reason 
> why I think all of these are wildly different, has to do with flow and 
> access trails. Ultimately, one might think docs will be generated using 
> some Javadoc++ process, as some novel language features in c# and Java, 
> and tools like xdoclet are trying to suggest. I'm still one of these 
> firm (silly?) believers that good user documentation is created with a 
> blank editor screen in front of you, and that a decently written 
> document of several screens long might be more helpful than the 
> technically correct, hyperlinked-to-the-max, autogenerated alternative.

Oh, I can't agree more. Believe me.

> For some examples, please see:
> 
> - http://xml.apache.org/forrest/your-project.html
> - http://xml.apache.org/forrest/linking.html
> - http://wiki.cocoondev.org/Wiki.jsp?page=DevelopingComponents
> - http://httpd.apache.org/docs-2.0/mod/mod_include.html
> - 
> http://www.zope.org/Documentation/Books/ZopeBook/current/SimpleExamples.stx
> 
> Nicola might be right in me being wrong, i.e. that I'm focusing too much 
> on the Cocoon website. If that is the case, I'm sorry, my view must be 
> warped then.
> 
>> In the future, i would like block-specific documentation to remain 
>> inside the blocks. Everything should remain as close as possible to 
>> the code: javadocs, tests, metadata in general even documentation, 
>> configurations, avalon roles, block metainfo and what not.
>>
>> creating a single docu repository is, IMO, a very dangerous road because:
>>
>> 1) it gives a perception that documents are maintained by somebody 
>> else. This perception is already here and it's probably my fault and 
>> this is causing pain and trouble to many people. I want this to be 
>> fixed in order for the process to be more scalable.
> 
> 
> I don't see the point in addressing a perception which surely isn't 
> generalized. Some people like to work on docs, and they will, and the 
> entrance barrier should be 'low enough' for them. Some people believe 
> plenty of Javadoc will do the job, alas to be read only by co-developers 
> IMHO. But we can't force anyone of them to become the other - we should 
> support both styles.

I agree.

> Making Cocoon user documentation independent of Cocoon itself might be a 
> good first step, that's why the Forrest transitioning is really, really 
> good.

yes

> I agree I said something like 'we the doco people'. What I meant was the 
> 'people usually contributing to documentation'. Some of them are 
> developers, some of them not.

I haven't contributed to documentation because I love xml but I bloody 
hate writing it and I love writing structured text but I hate the fact 
that wikis are so damn idiotic to navigate.

I want a serious CMS, damn it! with a dead-simple (not xopus!) inline 
editor on top! and using CVS as a repository! and transforming 
structured text in xdocs with perfect roundtripping!

And there's exactly where I want to push to go.

> My own belly tells me that people will write more and better user 
> documentation if they get some proper playground. Having to worry about 
> code sitting right beside their documents will not bring peace in their 
> minds.

Ok, please, explain to me why the cocoon CVS module is not a proper 
playground for people writing docs because I don't understand.

Stefano.



Mime
View raw message