forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steven Noels" <stev...@outerthought.org>
Subject RE: FAQ [was: Re: documentation architecture?]
Date Fri, 26 Apr 2002 08:09:01 GMT
Hi folks,

I've been away for a few days, and catching up...

I have some real-life experience setting up modular DTD's where UOI's
(Units of Information) are being assembled into 'consumable' documents:
while the result can be great, the burden it places on the shoulders of
the document editor mut not be underestimated.

Prior suggestions to tweak the DTD's have been opposed because of
'legacy' reasons... we indeed should not underestimate the amount of
available documentation already in xdoc format.

My remaining emotion about this opposing-views-discussion is that I'm
perfectly willing to massage DTD's into whatever direction we would
like, but that we should decide on the 'when': we have legacy, but if we
can convince more people to use Forrest because of the ease of
information entry, and we have to change DTD's for that purpose, I'm
perfectly happy.

With regards to Literate Programming (i.e. Javadoc as a starter for
'human' documentation): I'm not convinced this is the ideal approach...
the Cocoon documentation is in abysmal state partly because of the lack
of 'connecting' documents, which provide a flow in between the
component-based documentation snippets...

Just some thoughts while I'm catching up,

</Steven>

> -----Original Message-----
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> Sent: donderdag 25 april 2002 22:11
> To: forrest-dev@xml.apache.org
> Subject: Re: FAQ [was: Re: documentation architecture?]
>
>
> From: "Diana Shannon" <terracare@mac.com>
>
> >
> > On Thursday, April 25, 2002, Robert Koberg wrote:
> >
> > >>
> > >> 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.
> >
> > Ken, while you may be able to do this from a technological
> standpoint,
> > just how much value does it add to the user/reader
> experience? Think how
> > oppressive the style guide would have to be. Your "content
> blocks" would
> > have to be unbearably monotone so that they could fit into
> any document
> > context. This might work well for snippets of reference guides (with
> > notoriously volatile timestamps) as discussed recently on
> cocoon-dev.
> > However, I'd worry, in other cases, that you'd dampen the
> rich range of
> > styles and tones authors employ when writing by forcing them to
> > incorporate "official" content within their own works.
> >
> > Sometimes it's helpful to hear someone else say the same
> thing -- a bit
> > differently.
>
> Gee, I was starting to think that I was talking a different
> language ;-)
> I think you got my point :-)
>
> I see your point, but being programmer, I have the preconception that
> duplicating code is bad. That's why I *love* javadocs,
> because they put the
> information where it lives, and *only* there, in one place.
>
> I'll think about it a bit more.
>
> --
> Nicola Ken Barozzi                   nicolaken@apache.org
>             - verba volant, scripta manent -
>    (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------


Mime
View raw message