Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Date: Fri, 25 Mar 2005 10:59:39 +0100
From: Ferdinand Soethe <sammler@soethe.net>
Message-ID: <759575272.20050325105939@soethe.net>
To: David Crossley <dev@forrest.apache.org>
Subject: Re: [JIRA] Commented: (FOR-446) Dokumentation: HowTo Customize HTML
 Processing
In-Reply-To: <20050324093352.GA19687@igg.indexgeo.com.au>
References: 
 <25809993.1109190282075.JavaMail.jettyjira@strider.outerthought.net>
 <15078107.1111649898582.JavaMail.jettyjira@strider.outerthought.net>
 <20050324093352.GA19687@igg.indexgeo.com.au>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit


David Crossley wrote:

DC> They are really separate issues:
DC> 1) understanding the sitemap
DC> 2) customising the particular pipeline that processes html sources.

They could be if the text about the site maps was a general explanation
(which it isn't - yet?). Though in that case that text should not be a
HowTo but a normal document.

DC> We don't want to maintain another HowTo (which duplicates the content)
DC> the next time that we need to ensure that they understand how a
DC> pipeline works.

It's not really just about how a pipeline works. I knew that when I
started. But I found that you really need to understand the processing
concept above the pipeline level and how the different pipelines
interact together.

And so far, this metastructure is very specific to this particular
application of processing html. perhaps it could be generalized.

Yet if you do, that document on 'All Forrest Pipelines' might become a
lot harder to comprehend because it's a lot further away from the job
at hand.

DC> The annotated sitemaps that you started could also be linked from
DC> other documents, if we standardise the section names and anchors.

Might work if the request path for other documents is similar. We'll
see.

DC> So having separate documents, enables such re-use and we can do
DC> less work in the long run.

No doubt, that makes sense.

DC> We need to record those discoveries. However,
DC> each document does not need to explain everything.

That was the idea about it. My open question is wether you can
modularize knowledge like software and still expect non- or
-less-programmers to find there way into and through it.

My experience is that people are willing to learn if they have a goal,
so feeding them background knowledge on the road to that goal allows
them to learn easier and store that knowledge with the practical
application.

A general explanation of the sitemap in my experience is a lot harder
to digest.

Perhaps I had my target audience wrong here?

Ferdinand Soethe