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 20:04:46 GMT
From: "Diana Shannon" <terracare@mac.com>

>
> On April 25, 2002, 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.
>
> 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.

More effective structure +1
Existing content based on a specific need +1
Partially duplicating content because of this -0

If I have to write a paragraph that explains how to install on Weblogic and
then repeat myself partially in the FAQ when I explain that to avoid a
common problem while installing on Weblogic you have to do a specific thing,
I'm not happy.

Having to port the FAQ entry in the docs and keep it only there does not
make me happier.

> I also think we should encourage other types of "granular" content that
> could eventually be aggregated into more comprehensive documents.

+1

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

This comes nearer to my vision, but it's not quite it.

I'm trying to envision a totally different way of describing information.

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

With "problem ", I mean difficulty for the writers.
To make a book it's difficult to find the right balance between approaches.
But since we're making a (possibly) dynamic documentation system, we don't
necessarily have to choose beforehand.

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

This is the point for me.
Since our documentation can be used as a "teacher" itself (hey, we can make
a dynamic web application here, let's not forget!), we can think of how to
_guide_ our reader.

I repeat: it's /not/ a book, it's /more/ than a hypertext, it's a dynamic
infoset or whatever you prefer to call it..

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

"for its intended audience " means who/what/where  ;-)

I take for granted that the same person after a very short time is already
part of a different audience.

> > 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 ;) ?

Maybe I had too big expectations ;-)

The point is: do we really need to write reference guides, tutorials,
brochures... etc?
Can't we find a way to abstract information into something more granular so
that reference guides, tutorials, brochures, and so on, can be generated
_automatically_ from the same information source?

XML is content. XSL is view. Or only style?

There are high level information explanation systems, like transition trees
and current reality trees.
Can't we use them to represent-collate the information sets?

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

I'm not saying that I want to limit them.

Speaking in other /geeky/ terms, currently "classes of documentation" are
subclasses of a generic document.
The generic document defines paragraphs, strong text parts, lists, etc.
The FAQ class of documents can for example add a structure with sections and
faq-items, that inside use the parent class functionality (lists,
paragraphs, etc).

What I envision instead, is a different thing altogether.
There is *no* class Document, but a Document is solely an
aggregation-digestion of InformationPackets.
These Packets are correlated and described by cognitive and structural maps.
Different Maps represent different views on the same InformationSet
(collection of all the packets).

Documents are just a possible "style" for these views, and an automatic
voice system can be another (like cassette lessons).

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

I never aim low ;-)

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


Mime
View raw message