Add topic element to DocBook?

this discussion reminds me of the DITA for DocBook post

http://norma
n.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 <swhitlatgetnet.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:rajalmeshsoftware.com]
> Sent: Friday, October 27, 2006 9:02 AM
> To: 'Chris Chiasson'; 'Johnson, Eric'
> Cc: docbooklists.oasis-open.org
> Subject: RE: [docbook] Add topic element to DocBook?
>
>
>
>
> Comments inline..
>
>
>
> -----Original Message-----
> From: chris.chiassongmail.com
[mailto:chris.chiassongmail.com] On Behalf
> Of Chris Chiasson
> Sent: Friday, October 27, 2006 8:51 AM
> To: Johnson, Eric
> Cc: docbooklists.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.nam
e/

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

this discussion reminds me of the DITA for DocBook post

http://norma
n.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 <swhitlatgetnet.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:rajalmeshsoftware.com]
> Sent: Friday, October 27, 2006 9:02 AM
> To: 'Chris Chiasson'; 'Johnson, Eric'
> Cc: docbooklists.oasis-open.org
> Subject: RE: [docbook] Add topic element to DocBook?
>
>
>
>
> Comments inline..
>
>
>
> -----Original Message-----
> From: chris.chiassongmail.com
[mailto:chris.chiassongmail.com] On Behalf
> Of Chris Chiasson
> Sent: Friday, October 27, 2006 8:51 AM
> To: Johnson, Eric
> Cc: docbooklists.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.nam
e/

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org