forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [JIRA] Commented: (FOR-446) Dokumentation: HowTo Customize HTML Processing
Date Fri, 25 Mar 2005 11:13:07 GMT
Ferdinand Soethe wrote:
> 
> David Crossley wrote:
> 

...

> 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.

As a (past) specialist in educational materials I will say that this is 
the holy grail of training materials. We haven't found it yet.

I've not yet read the How-To since it was split so I won't comment 
directly on whether I think that split works or not. But I will say 
something about an annotated sitemap. Consider this:

<!-- Processes all requests for HTML documents by first generating
a document that will contain X, transforming it to make it contain Y.

This match will usually be called by the [client|another pipeline].

See http://forrest.apache.org/docs/howTo/HOWTO_DO_THAT.html and 
http://forrest.apache.org/docs/processingHTMLRequests.html for more details
-->

Will be of use in a fairly wide range of applications. The focus is on a 
summary of the actions and is intended to prevent the need for the 
reader to go and find other pipelines to work out what a <map:generate 
src="cocoon://SOMETHING"/> does, they can simply read the one line 
summary. similarly they won't need to open the stylesheets to see what 
they do because there is a one line summary.

How-To documentation will provide a more detailed and specific 
description of how it works.

This makes the sitemap.xmap file readable at the same time as extracting 
generalise comment to a central location.

> 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.

Absolutely, but equally, if you know the background you should be able 
to quickly skip over it and get to the new knowledge. Having 
prerequisites for a course is common practice to enable this to happen.

Does the How-To have a perquisites section? If not it should do.

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

I would agree that a general explanation is not relevant to a How-To 
document, here we need to focus on the task in hand. However a reference 
document should be generalised in order to keep the information concise.

> Perhaps I had my target audience wrong here?

No, I think you had it exactly correct. However, you are the first to 
tackle such low level docs in a very long time (and boy do we need it). 
All other docs (including my own) have focused on just the specific task 
and have assumed that the reader has a base understanding.

Since you are targeting a specific audience that we have so far 
neglected we are "wondering aloud" if we can make the job easier in the 
long run. It's easier to get it right now than it is to change it after 
you have written us another 5 great how-to's like that one/two.

Ross

Mime
View raw message