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
|