cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <>
Subject Re: "Apache Cocoon in Action" suggestion and call for opinions
Date Thu, 14 Apr 2005 12:09:07 GMT
Sebastien Arbogast wrote:
>>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....

We (I) know that writing docs isn't as convenient as it could be (although it 
has become much easier) and I plan to support higher-level documentation editing 
in the future.

Have a look at 
where my idea of an "online editing" is explained. For lack of time I haven't 
started with it yet but it's definititly on my todo list.

Reinhard Pötz           Independent Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}


View raw message