> RAJAL
> Topic - as we're discussing
here - is a semantically meaningful standalone piece of
content..
However, no
hunk/chuck/topic/piece/paragraph/book/section of documentation stands alone, and
in a sense everything is semantically meaningful. So, what is
the meaning of "topic"? Would it be everything and anything and
belong anywhere?
How
are writers supposed to write intelligible "stand-alone" material, considering
that sequence and context are so important for learning. This is a
rhetorical question for the newsgroup, but I did specifically ask this very
question of Don Day (DITA architect). His answer was that writers would
need to change their thinking.
That's
when I stopped my efforts with DITA, so I don't know a great deal about it, or
if or where DocBook can use a <topic> element. But OK, I can
imagine documentation with sequence being out, meaning that a
writer cannot rely upon the reader having the foundation of previous material
and cannot depend upon any specific
hunk/chuck/topic/piece/paragraph/book/section to appear in specific
context(s). OK.
The
result I imagine as a spaghetti of links. It sounds bad, but in
practice it seems to work good. The IBM DB2 "Information
Center"(s) are authored in a DITA environment, or at least that is what I was
told. My apologies if I am wrong about this. I think they are fine examples
of good documentation.
http://publib.boulder.ibm.com/infocenter/db2luw/v8//index.jsp
I see
logical sequences in that documentation. Maybe that is what the DITA map is
for.
Steve
Whitlatch
-----Original Message-----
From: Rajal Shah
[mailto:]
Sent: Friday, October 27, 2006 9:02
AM
To: 'Chris Chiasson'; 'Johnson, Eric'
Cc:
Subject: RE: [docbook] Add topic
element to DocBook?
Comments inline..
-----Original Message-----
From:
[mailto:] On Behalf Of Chris
Chiasson
Sent: Friday, October 27, 2006 8:51 AM
To: Johnson, Eric
Cc:
Subject: Re: [docbook] Add topic element to
DocBook?
I haven't checked this, but I think section is not
allowed as a root
element. This means that documents beginning with
<section> will
require a DocBook schema customization to validate. I
have had this
problem with documents that begin with
<equation>.
Maybe it would be better if someone who actually wants
<topic> to make
a case for it?
>>>>>
RAJAL ->
Topic - as we're discussing here - is a
semantically meaningful standalone piece of
content..
It greatly facilitates modular writing,
where we're not just focused on books but individual units of information..
The style of writing in the book changes from being a single flow from
beginning-to-end to instead be a collection of topics.. This allows
organizations (I work at Juniper), to provide their content in book form as
well as searchable topics on the web or for re-use of content
elsewhere.
Does that make a high-level case for
having <topic>?
Having said that, once we move to the
topic world, people will need have the need for their own topic types.. For
e.g. at Juniper we have: <command-summary>, <verification-task>,
<example>, <procedure>, <trouble-shooting> etc.. The reason
is that once we agree on the idea of standalone topics/modular writing,
semantically meaningful topic elements and their structure gets important for
authors - who are now assigned to topics and not be a book-owner as such.. I
am hoping that DocBook can standardize some of them too at some point..
J
Regards.
--
Rajal
