Re: [docbook] Add topic element to DocBook?

["Chris Chiasson" <chris@chiasson.name>]

this discussion reminds me of the DITA for DocBook post

http://norman.walsh.name/2005/10/21/dita

how many advantages of DITA will eventually end up in DocBook?

what damage will be done to DocBook by including them?

On 10/27/06, Steve Whitlatch <swhitlat@getnet.net> wrote:
>
>
>
>
>
>
>
> > 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
>
>
>
>


-- 
http://chris.chiasson.name/