forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: Understanding linking
Date Mon, 09 Aug 2004 12:04:21 GMT
Charles Palmer wrote:
<snip/>
> 
> I'll rework my sample2.xml if you like, but it sounds like you are already
> cutting and pasting this to other places.

No wait. Once you submit something you would need to give
us a chance to rework it and incorporate it. Then you can
get the new source and build upon it. Just save your ideas
in a text file for now, then add them later.

> Could I clarify my earlier point about the use of examples and the location
> of documentation:
> 
> In my experience learning and understanding a new concept is much easier if
> the documentation describes a working example that I have at hand, and can
> modify to extend the example to fit my actual needs.

I agree entirely, and i work this way too.

We have established the shell of an example site.
The next stage is to flesh it out with worked examples.

There is a trade-off with how much actual documentation
and explanation to put in there. It would be better to be
concise, and have the lengthy explanations in the core docs.
The core docs are what compose our final website. It is good
to have the documentation in the open and so not need to
duplicate.

Now here is an idea. We could generate the seed site docs
and put them online as part of the website. That way we
only need to document in one place ... a self-describing
example site.

> That is why (IMHO) it
> is very useful to have the documentation (wherever it is located) refer to
> examples provided within the material generated by the forrest seed process.
> That way I can take real source files on my computer and learn by changing
> them. If the documentation refers to examples within the main forrest site
> then I can't (easily) learn by making changes to them.

Well you can do that too. You have a local copy of the
core docs. You can tweak it and send patches to us.

> It is less important whether the forrest seed material is self documenting,
> or whether I have to go elsewhere for the documentation. What is really
> valuable is if the documentation refers to source files that I have readily
> at hand.
> 
> Note that this might mean making the structure of the forrest seed site
> slightly more complex, so more general examples can be given as well as the
> most trivial case.

Your ideas are good. We can build on the infrastructure
that we have. Perhaps we can can different seeds to suit
various circumstances.

-- 
David Crossley


Mime
View raw message