forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: FAQ [was: Re: documentation architecture?]
Date Thu, 25 Apr 2002 18:09:54 GMT

On April 25, 2002, Ken Barozzi wrote:

> From: "Diana Shannon" <>
>> IMO, FAQ content should primarily address holes or ambiguity in other
>> documentation, as well as bugs in code.
> Not necessarily.

Are you trying to say that FAQs have come to represent the smallest 
granularity of information in a documentation project? If so, I 
certainly agree with you. I'm just arguing for more effective structures 
for new content as well as existing content based on a specific need.

I also think we should encourage other types of "granular" content that 
could eventually be aggregated into more comprehensive documents. One 
example is a "Mini-How-To," a document which describes how to accomplish 
a specific task in a consise, action-oriented fashion. The presence of a 
number of similar Mini-How-Tos (variations on a the same topic) may 
reveal the lack of a user comprehension of a design pattern. Thus, a new 
concept document or tutorial might focus on teaching the design pattern, 
using the Mini-How-Tos as examples. Or, let's say you have cookbook 
"recipes" (code snippets with some explanation) submissions. These could 
be migrated into/referred to by a "best practices" guide/tutorial/other 

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

Documents *solve* problems. A poorly written, weakly designed, or 
missing document is a problem.

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

These are all "methods" used by authors of training/tutorial documents. 
Their degree of effectiveness depends on how and when they are applied. 
Some methods work best with specific types of content/subject matter or 
at a certain point in time (in the learning process). Good writers know 
how to provide the right balance and sequence of theory, analogy, and 
example. They also know how to anticipate common questions as well as 
help users recover from common mistakes. I still think the effectiveness 
of a document -- for its intended audience -- is a concrete result of 
its design, not a function of who/what/where.

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

A single document isn't supposed to address all possible use cases. 
That's why we have reference guides, tutorials, brochures, newsletters, 
etc. Maybe you're being too critical of yourself as the author ;) ?

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

Don't you think that's more a reflection of your evolution as a learner? 
I don't think it's a good argument for limiting the classes of documents 
we might develop.

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

That's a lofty goal.


View raw message