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 18:56:21 GMT
Nicola Ken Barozzi wrote:

>From: "Robert Koberg" <rob@koberg.com>
>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".
>

I have seen nothing from her about 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.
>
this makes perfect sense. But i see you concern now after reading the 
thread. I see the FAQ as one entry point to more documentation

>
>
>What I envision instead is that ALL the documentation can be seen and read
>in different ways, different views.
>
I just assumed this is the way it would be...

>
>
>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
>weblogic?".
>Or in the tutorial: "Now install Cocoon. If you have weblogic...".
>
OK, sure. Or it could easily be a link. Whichever makes more sense. I 
would think a summary (taken from the main docs) and a link to further 
info would make more sense because it takes them out of a chaotic 
environment and brings them to an area that deals with specific needs.

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

Maybe I am wrong, but I thought the whole premise of XML was resuable 
content abstracted from the presentation. I assumed this was a given, 
where it is appropriate. But, you should not try to fit square pegs into 
round holes.

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

Whatever... I was helping myself because I agree with her approach...

best,
-Rob



Mime
View raw message