forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Koberg <...@koberg.com>
Subject Re: FAQ [was: Re: documentation architecture?]
Date Thu, 25 Apr 2002 15:24:05 GMT
Hi,

It sounds like you just restated what she is trying to do.


Nicola Ken Barozzi wrote:

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

Where do you go on to refute this? She seems to be right on with 
everything she has proposed so far.

Everything you describe below has already been described by Diana??

best,
-Rob

>
>
>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 pa
Mime
View raw message