RE: [docbook] Add topic element to DocBook?

["Steve Whitlatch" <swhitlat@getnet.net>]

 

> 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:rajal@meshsoftware.com]
Sent: Friday, October 27, 2006 9:02 AM
To: 'Chris Chiasson'; 'Johnson, Eric'
Cc: docbook@lists.oasis-open.org
Subject: RE: [docbook] Add topic element to DocBook?

Comments inline..

 

-----Original Message-----
From: chris.chiasson@gmail.com [mailto:chris.chiasson@gmail.com] On Behalf Of Chris Chiasson
Sent: Friday, October 27, 2006 8:51 AM
To: Johnson, Eric
Cc: docbook@lists.oasis-open.org
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