forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nicola Ken Barozzi" <nicola...@apache.org>
Subject Re: FAQ [was: Re: documentation architecture?]
Date Thu, 25 Apr 2002 14:57:21 GMT
From: "Diana Shannon" <terracare@mac.com>

> IMO, FAQ content should primarily address holes or ambiguity in other
> documentation, as well as bugs in code.

Not necessarily.

The main problem of a documentation is that it can be written in different
ways, which have a varying degree of effectiveness depending on /who/ reads
them and /when/.

Let me try to explain a bit more.

As an example take any school book.

It can teach the same content by:

1. explaining the theorical architecture and providing corresponding use
cases
2. teaching the history of how the theory got made with all the real life
things that provided the insight needed
3. answering questions that users might pose as the learning advances
4. providing clever use-cases that make the student get more insight as the
explanation advances (learn by doing)
5. etc...

I've seen this when I wrote a short book on how the computer works, called
"Computer Architecture".
It has been useful for many as a reference, and in part as a support for
teaching, but can't be read by itself to learn how to use a Computer.

Every time I read a technical book in my life, I always understand more
things and in a different way.

What I'm trying to say is that we should find a way of abstracting the
information in such a way that it can be relaborated and shown to the user
in many ways, so that we open different communication channels to the same
knowledge.

What is the smallest unit of information for a Java project?
What knowledgemap is needed to bind these together?
What are the communication channels that can be used to render this
knowledgebase?

Am I starting to see a use for RDF and TopicMaps? ;-)

> They also provide a useful
> (though not always optimal) way to update the document set. They can
> also give people a quick overview of a project/software. What else
> should they address -- in an ideal world?
>
> I also think the FAQ dtd needs "last modified" content (as per David's
> earlier suggestion on cocoon-dev).

+1

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message