Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: pass (hermes.apache.org: local policy includes SPF record at
 spf.trusted-forwarder.org)
Message-ID: <425E5D63.3030707@apache.org>
Date: Thu, 14 Apr 2005 14:09:07 +0200
From: Reinhard Poetz <reinhard@apache.org>
User-Agent: Mozilla Thunderbird 0.9 (Windows/20041103)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: "Apache Cocoon in Action" suggestion and call for opinions
References: <a753b7f80504122210878087b@mail.gmail.com>
	 <31b8d10b733f12b13c0f2cc3f684ead0@apache.org>
	 <a753b7f80504132247362876a6@mail.gmail.com>
	 <ad780a4819b88e1c22a7aad2789cd083@apache.org>
 <a753b7f80504140429507e7255@mail.gmail.com>
In-Reply-To: <a753b7f80504140429507e7255@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 8bit

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 http://wiki.apache.org/cocoon/CocoonDocumentationSystemSUMMARY 
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}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------