forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [JIRA] Commented: (FOR-446) Dokumentation: HowTo Customize HTML Processing
Date Thu, 24 Mar 2005 09:33:52 GMT
>   http://issues.cocoondev.org//browse/FOR-446
> The following comment has been added to this issue:
> 
>      Author: Ferdinand Soethe
>     Created: Thu, 24 Mar 2005 1:38 AM
>        Body:
> Thanks for the feedback.
> 
> Re splitting
> 
> The reason I did not split them after some consideration,
> is that you really need to understand what happens to be able
> to customize the pipeline documents properly (in fact that's how
> I learned all this because I found that Ross just telling me
> what to do will raise further questions right away).
> I'd be interested to know why you changed that.

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

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

As i did with your "custom html" howto, we make it a <prerequisite>
that they read the "understanding pipelines" howto. Perhaps that
needs to be emphasised in the first Step.

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

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

You say that you "learned more". This is one of the big benefits
about writing docs. It happens to me every time i attempt to write
even a "small FAQ" - i discover more about forrest that would have
helped to have known. We need to record those discoveries. However,
each document does not need to explain everything.

Anyway, if people don't agree, then we can change it.

--David

Mime
View raw message