Why did I choose DocBook for ForgeRock core docs instead of something more modular?
Theoretically assemblies and transclusion are coming to DocBook, so it ought to be possible to have one’s book and modules, too. But that is not why. It will be challenge enough to get inter-document links working properly and simply, let alone managing assemblies in a way that does not scare off occasional authors.
Did I choose DocBook because I know it. Honestly, that is part of it. Other people know it, too. The Linux Documentation Project chose DocBook. IIRC the web was kind of 1.x at the time the choice was made, but they could have chosen TeX, for example.
A content management system could be a good choice, perhaps.
Deep down though, I suspect that although people do not want to read technical documentation — We all want someone else to show us how to work with software that is new to us, or to paste an error message verbatim into the search engine and see the solution instantly. — sometimes we get stuck and have to read.
Theoretically this happens very seldom. I used to have a quote on the door of the office from The UNIX-HATERS Handbook, “People vote for president more often than they read printed documentation.” That is not quite true anymore, because so many people just do not vote.
When we get stuck and have to read, unless we already know enough to frame the query that calls up the solution from some corner of the Web, we wish someone would explain from the beginning (wherever the beginning is for us) and continue, quickly, to the end. We want an elucidating explanation, such that we are not investing valuable time just to follow a recipe, but instead investing to get the hang of how to do that particular kind of cooking. So that we will not have to read again next time.
If the docs were essentially for policies and procedures, with architects who already know needing notes for operators who do not want to know, then okay, modules would be fine. We aspire, however, to share understanding with developers and partners like you. For that we cannot get around crafting books.
Margin Notes 2.0 