cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sebastien Arbogast <sebastien.arbog...@gmail.com>
Subject Re: "Apache Cocoon in Action" suggestion and call for opinions
Date Thu, 14 Apr 2005 11:29:41 GMT
> I don't mean the docs have to be made up of small chunks, but it must
> be possible to do useful work on them in small amounts of time (which
> is perfectly possible with the 2.2 docs system).

Let's think in terms of network architecture and layers. I personally
think that what Reinhard and Upayavira with the 2.2docs system is
perfect as a basis, as a low level architecture layer to work upon.
But as I see it, it's still too far from the potential documentation
writer, especially for that kind of global "high-level" tutorial we
would like to build here. I mean for you and me and the vast majority
of Cocoon developers, we know how to check out sources from SVN
repository, we know what forrest is and we know how to edit HTML
files. As for communication, we can surely use mailing list and wiki.
So when you are a developer, you can write documentation. But is the
assumption true the other way round ? I don't think so. I really don't
think that one should need all of that to write documentation and to
collaborate with others. It's necessary but it's too low-level, so for
newcomers it is discouraging, and for us it totally lacks
productivity.

That's what I would like to try with this initiative : build a quick
overlayer to make the link between potential documentation writers and
the development architecture. This layer will provide all the
communication and collaboration services that are missing with current
tools: organized message boards, workflow and resource management and
the most important for me, coding architecture abstraction. There are
tools that make that it very easy to build that kind of community
platform and I'm trying to work things out with a CMS. It won't be
long and we are already talking about the first steps of our work so
it should start quite soon.

> Don't get me wrong, your enthusiasm is very welcome, but I think the
> tools available now (html editing, Forrest for previews, svn + lists +
> wiki for collaboration) are good enough to do useful work. But if the
> community does not have enough "collective energy" to do the work,
> nothing happens.

I totally agree with your concept of "collective energy", but when
collective energy dissipates in technical details frictions, it often
remains quite low compared to what it could be if things were...
easier.

> Let's get something done with the tools in place today before declaring
> them inadequate - the improved infrastructure created by Reinhard,
> Upayavira and others is just starting to bear fruit, building on this
> makes a lot of sense, but *content* needs to be created.

I insist on that once again. I don't consider current tools as
inadequate, they are essential but using them directly leads to some
very annoying things such as those we can read on the wiki for example
: non-terminated tutorials, no table of content, no common styling or
structure, no versioning of documents or lifecycle management. It's
better than nothing but once again, for the kind of complete tutorial
we plan to write, it doesn't fit.
So we will totally integrate with common tools, but for now we plan to
use an intermediary platform to analyze and build the content, to get
it to a nearly-finished state before writing things on the wiki or
making a request in bugzilla. That's the general idea...

When you want to go from one side of the river to the other side, you
can dive and swim, or you can quickly build a pirogue that will be
more efficient, that will be able to carry many more people and scare
far less....

-- 
Sebastien ARBOGAST

Mime
View raw message