You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Steven Noels <st...@outerthought.org> on 2003/03/24 15:15:05 UTC
[rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
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?
> 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.
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
* 'user' documentation, like 'building new Cocoon components', or
'installing Cocoon on Znorbaf appserver'
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.
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.
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.
This all IMHO.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Andrew Savory wrote:
> On Mon, 24 Mar 2003, Stefano Mazzocchi wrote:
>
>>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!
>
> +1 from me! I do think having a cocoon-docs CVS would help rather than
> hinder this though, as we could easily allow updating of the documentation
> with no danger that any of the code might be attacked by an errant CMS.
Yes, I was thinking exactly this when I changed my vote, even if I don't
think that the apache infrastructure will ever allow a CMS to become
*committer* to the CVS repository.
however, separating documents from code in different modules, would
allow (in theory, at least) to setup a CMS that has commit priviledges
only on the documentation module, thus leaving the code fully protected
from potential exploits of the CMS.
If there is *one* single change of having such CMS cleared by our
infrastructure team, separating the modules will sure increase this
chance, not reduce it.
This is, IMO, the biggest argument in favor of such a separation.
Stefano.
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Andrew Savory <an...@luminas.co.uk>.
Hi,
Just to add my thoughts to this. Regarding transition to 2.1 making 2.0
docs obsolete - this is a fair comment, but what do we do when we start
working on 2.2?
I do appreciate Stefano's comments about blocks though, and how code and
documentation in that instance belong together, and to be honest, this
wasn't something I'd thought about. I don't see any easy answer to that
other than that the documentation that goes with the blocks should be
javadoc-style only, and reference/howto material belongs in the main docs
tree. It would be annoying to have to grab block X just to get the
documentation for it, when following links in the documentation you do
have.
On Mon, 24 Mar 2003, Stefano Mazzocchi wrote:
> 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!
+1 from me! I do think having a cocoon-docs CVS would help rather than
hinder this though, as we could easily allow updating of the documentation
with no danger that any of the code might be attacked by an errant CMS.
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Diana Shannon wrote:
>
> On Monday, March 24, 2003, at 10:34 AM, Steven Noels wrote:
>
>>
>>>> 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.
>
>
> A few Belly Thoughts:
>
> + Consider what we are about to implement in 2.1. Forrest generates our
> web site and docs, based on the contents of xdocs. What if docs people
> want to experiment? How can we do that if the place where docs live,
> next to code, it automatically considered final by our publishing
> mechanism. Therefore, all experiments either break the automatic
> publishing or get published to the web (which we may not want).
>
> + What about prototyping new doc approaches, like reference pages for
> logicsheets, as Andrew recently proposed. What if we need some special
> jar for that, something totally related to docs, not the cvs. Where
> shall we put it? Bloat the code repo for docs-only needs? Put it in
> Forrest? Well, what if it's outside the "concern" of Forrest or we don't
> want to wait for Forrest -- e.g. experiment a little internally?
>
> + CMS issues, already raised in previous posts.
>
> + What if we start some global docs transition, say based on adding
> Dublin Core data, etc. What if we have only a partial set of docs
> changed over. Wouldn't a docs module, with an experimental/head branch,
> be a great place for this collaboration?
All right.
I'm changing my vote from -1 to +1. I trust the people wanting this
enough to appreciate the fact that they might point out that I'm wrong
and I'm not seeing where the problems are.
I hope that others reconsider their vote.
Stefano.
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Diana Shannon <sh...@apache.org>.
On Monday, March 24, 2003, at 10:34 AM, Steven Noels wrote:
>
>>> 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.
A few Belly Thoughts:
+ Consider what we are about to implement in 2.1. Forrest generates our
web site and docs, based on the contents of xdocs. What if docs people
want to experiment? How can we do that if the place where docs live,
next to code, it automatically considered final by our publishing
mechanism. Therefore, all experiments either break the automatic
publishing or get published to the web (which we may not want).
+ What about prototyping new doc approaches, like reference pages for
logicsheets, as Andrew recently proposed. What if we need some special
jar for that, something totally related to docs, not the cvs. Where
shall we put it? Bloat the code repo for docs-only needs? Put it in
Forrest? Well, what if it's outside the "concern" of Forrest or we don't
want to wait for Forrest -- e.g. experiment a little internally?
+ CMS issues, already raised in previous posts.
+ What if we start some global docs transition, say based on adding
Dublin Core data, etc. What if we have only a partial set of docs
changed over. Wouldn't a docs module, with an experimental/head branch,
be a great place for this collaboration?
Diana
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Steven Noels <st...@outerthought.org>.
On 24/03/2003 16:09 Stefano Mazzocchi wrote:
(About pointy tags: send over your p-Book and I'll install XXE for you.
XXE reminds me of why I am so reluctant to believe browser-based widgets
will never be able to edit anything else but semantically poor
(X)HTML-like fragments)
>> 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.
1) up to lately, the docs target has been failing on quite some occasions.
2) up to lately, the 'requirement' (?) to sync branches brought even
more relunctancy.
3) there's too much documentation already (!): people prefer a
clean-sheet approach (look at the Wiki, and don't think all of it is
'draft' or 'playground') - particularly on the entry level
documentation/trails
4) up to lately, the entire Cocoon CVS module was needed to work on
documentation. Now, people could possibly check-out only
src/documentation and work on that using a binary install of Forrest.
5) (minor) some of the docs can hardly be concerned authorative
(http://xml.apache.org/cocoon/tutorial/index.html) and should not be in
Cocoon CVS
All in all, most of my playground them has to do with it 'being vacant',
rather than technics or tools.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [rant] Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 25/3/03 9:23 am, "Stefano Mazzocchi" <st...@apache.org> wrote:
> Pier Fumagalli wrote:
>> On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>>
>>
>>> 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.
>>
>>
>> Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still a
>> lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
>> more performance than the old tree...
>>
>> Still, a huge part of the user base didn't "switch" just yet...
>
> key words: 'just yet'.
Gotcha...
> I didn't say "how long". AFAIK, many people are still using Cocoon 1.8.2
> in production and it's been running for two years without failing once.
>
> Yet, everybody considers Cocoon 1.x dead and no development is taking
> place anymore and nobody objects it.
>
> Cocoon 2.0.x will remain there potentially for years and will be used
> for many more in production environments.
Like us at VNU, where we still are running a couple of httpd 1.2.6 :-)
> Still, if development doesn't move on and transition isn't smooth, we
> are actually forking the project.
>
> If development on HTTPD continues on both fronts, they failed since the
> community shows that 2.0 is nothing better than what they already had.
>
> i don't think this is the case, I think it's just a matter of time.
>
> As it will be for Cocoon 2.1.
I'd say: as it is _already_ for Cocoon 2.0/2.1... Since we split the repos
(and if I'm not wrong), we had 32 commits to the 2.0 repo, more than 370 to
the 2.1 one... So... We're all happy campers! :-)
Pier
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
Pier Fumagalli wrote:
> On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>
>
>>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.
>
>
> Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still a
> lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
> more performance than the old tree...
>
> Still, a huge part of the user base didn't "switch" just yet...
key words: 'just yet'.
I didn't say "how long". AFAIK, many people are still using Cocoon 1.8.2
in production and it's been running for two years without failing once.
Yet, everybody considers Cocoon 1.x dead and no development is taking
place anymore and nobody objects it.
Cocoon 2.0.x will remain there potentially for years and will be used
for many more in production environments.
Still, if development doesn't move on and transition isn't smooth, we
are actually forking the project.
If development on HTTPD continues on both fronts, they failed since the
community shows that 2.0 is nothing better than what they already had.
i don't think this is the case, I think it's just a matter of time.
As it will be for Cocoon 2.1.
if a project creates a new generation and their development base splits,
they are, in fact, forking the project.
See Tomcat.
This is the *worst* thing that can happen to an open source project.
Luckily, Apache is very tollerant at forced cohabitation and eventually,
split development bases remerge down the road.
Stefano.
Re: [rant] Re: [vote] micro-decision for docs: creation ofcocoon-docs CVS module
Posted by "J.D. Daniels" <jd...@datatrio.com>.
Actually... I dont httpd is a fiar example. There is a reason for that...
there is not many modules that function correctly under 2.0... we are only
waiting for them to catch up :D at my last count, there are 4 that i use
that dont work. (Among them mod_jk)
By itself, 2.0 kicks butt... but i can't use it in production yet :(
JD
----- Original Message -----
From: "Pier Fumagalli" <pi...@betaversion.org>
To: <co...@xml.apache.org>
Sent: Monday, March 24, 2003 12:04 PM
Subject: Re: [rant] Re: [vote] micro-decision for docs: creation
ofcocoon-docs CVS module
> On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
>
> > 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.
>
> Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still
a
> lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
> more performance than the old tree...
>
> Still, a huge part of the user base didn't "switch" just yet...
>
> Pier
>
Re: [rant] Re: [vote] micro-decision for docs: creation of
cocoon-docs CVS module
Posted by Pier Fumagalli <pi...@betaversion.org>.
On 24/3/03 3:09 pm, "Stefano Mazzocchi" <st...@apache.org> wrote:
> 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.
Hmm.. I don't think you're right on this, Stefano... Look at HTTPd, still a
lot of people are using 1.3, when 2.0 is delivering (for example) _A_LOT_
more performance than the old tree...
Still, a huge part of the user base didn't "switch" just yet...
Pier
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs
CVS module
Posted by Stefano Mazzocchi <st...@apache.org>.
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.
Re: [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Posted by Diana Shannon <sh...@apache.org>.
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