forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nicola Ken Barozzi" <>
Subject Re: FAQ [was: Re: documentation architecture?]
Date Thu, 25 Apr 2002 17:52:41 GMT
From: "Robert Koberg" <>

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

Dunno, I'm trying to convey something new, but if it's already said then
even better, I'm +1 with it ;-)

> Nicola 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.
> >
> Where do you go on to refute this? She seems to be right on with
> everything she has proposed so far.

Maybe I haven't explained myself well enough, but I *did* refute this in
what I wrote.
Not that here vision is not sensible, I'm just trying to bring the
documentation system of a project further than "a book online".

Diana seems to be talking about different sections that each give an extra
contribute to the docs.

"address holes in the documentation" means that the FAQ contains information
that is not in the general documentation, which implicitly has "holes".

Also: "However, over time, I think FAQ
content should migrate to more appropriate document types: how-tos,
guides, tutorials. ", which in means that the FAQ is a sort of
well-organized forum.

What I envision instead is that ALL the documentation can be seen and read
in different ways, different views.

For example, let's say that in the docs there is a paragraph about how to
install Cocoon on Weblogic.
There could be a question in the FAQ that says "how do I install Cocoon on
Or in the tutorial: "Now install Cocoon. If you have weblogic...".

As you see, the *same* piece of information is conveyed in different ways.
The *same*, no need to rewrite anything.

On this list I haven't yet seen Diana say this, correct me if I'm wrong.

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

Is this a question?
I don't think Diana needs to be helped, she is more than able to speak for
herself, thank you.

Nicola Ken Barozzi         
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)

View raw message