cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Date Mon, 24 Mar 2003 16:14:51 GMT

On Monday, March 24, 2003, at 09:15  AM, 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?

Furthermore, there will be differences between 2.1 and 2.2 that 
inevitably emerge ... I personally think transition periods between 
software versions are the rule, not the exception. Docs which can point 
out the differences are helpful, especially to new users. It would be so 
easy with a single set of docs. I've worked with Cocoon since 1.7. In my 
experience, we've always been transitioning. I think it's particularly 
hard it is for users to get up to speed with such differences. Our 
changes doc is overly terse for new users.

>
>> 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.

In some ways, you could argue the "genie is already out of the bottle." 
Look at CocoonWiki (where docs are "far away" from code). Does anyone 
realize there are 44 How-Tos there? Now compare that to our cvs count: 
12 (with only half being technical, e.g. not 
administrative/editorial-oriented). Interesting.

<snip what="doc types" why="agree with Steven" />

>> 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.

But in some ways **many** docs are already being maintained by "somebody 
else" -- our users on wiki. Where documents "live" in some ways should 
be secondary to how to provide the best access to those who want to 
improve them. However, I still can't see a future CMS which reads/writes 
a majority of its doc content from a code repository. It simply makes no 
sense to me, from a SoC point of view. Some may argue, well we don't 
have a CMS yet, but a "poor man's" CMS seems very doable now, given the 
excellent work already available from many on this very list.

>> 2) it has a short-term impact on a short-term problem that is an 
>> evidence of a much bigger problem: our inability to do faster 
>> releases. we should design the entire system to allow us to make 
>> faster releases and this should be our goal, even if potentially 
>> disruptive for the short term.
>
> 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.
>
> Making Cocoon user documentation independent of Cocoon itself might be 
> a good first step, that's why the Forrest transitioning is really, 
> really good.
>
> 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.
>
> 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.

+1 Well stated.

Diana


Mime
View raw message