State of topic oriented writing in DocBook?

Thomas Schraitle <[email protected]> Wed, 30 Nov 2022 10:49:41 +0100
Newsgroups gmane.text.docbook.misc
Message-ID <[email protected]>
Hi,

as the documentation world uses more and more a topic-oriented approach,
solutions are being sought that do justice to this approach. Also for DocB=
ook.

As DocBook wants also be part of that idea, it created assemblies which is
good. On the other side it seems it is only partly prepared for such an
approach. Especially if we compare it to DITA, TEI, and others.

One example is the use of XIncludes which is great. It allows to include
content from other files. We can even include such content twice. However,=
 it
only works if we not have IDs twice otherwise we get duplicate ID errors.

We can use transclusion attributes or an assembly file which makes it easi=
er to
write topics and combine them. On the other side, it can be hard to write =
and
maybe it does not cover all use cases.

Sooo... I gives me the impression we still aren't fully there: DITA has
conrefs, keymaps, and other fancy issues. Certainly not all are needed, bu=
t
these are one of the things that lacks DocBook. Or am I missing them?

To make a long story short: how is the current state of topic oriented wri=
ting
in DocBook? What's still missing in the DocBook schema and the stylesheets=
?
What is DocBook willing to support? Can some DITA features be replicated i=
n
DocBook (like the mentioned conref and keymaps)?

For example, we are trying to move our documentation to a more topic orien=
ted
approach. We don't want to move to DITA as all of our writers know DocBook=
. We
aren't fully there yet, but would like to continue with our existing DocBo=
ok
toolchain. Would like to mix our topics and have an assembly for creating =
the
result. Unfortunately, <topic>s can't be nested. ID fixup is another issue=
,
it's not really supported yet.

It's sometimes frustrating to see that DocBook is halfway there but is mis=
sing
this extra mile that you need. I would really like to see solutions in Doc=
Book
that supports a more topic oriented writing experience.

I hope it doesn't sounds too negative. :) I intentionally focused in this
e-mail on a more high-level overview to not bore you to death with details=
 and
keep this post short. ;)

So what's your take on this? How do you use DocBook for an topic oriented
approach? Are you happy? What are you missing? Am I wrong?

Thanks for your thoughts. :-)

=2D-
Gru=C3=9F/Regards
   Thomas Schraitle