briandominick
commented
5 years ago Your crtique here is very solid. Part of me has been thinking I have no business writing "in general", for reasons becoming clear here. But you're right, whenever I do, I need to step out, and make sure AsciiDoc examples are just that.
As for how far down the dynamism hole I want to go, you're singing my tune. I'm constantly crowing about user-customizable docs (though not much in this manuscript yet, if at all). Know of any real-world examples!?
I haven't seen LwDITA in practice. Last time I tried to check on it, I had the impression the standard was still being fussed over? Is there software!? That is very exciting. I am certainly all-for DITA catching up in this regard.
Anyway all your points here are very well taken. Do you think I should be focusing more broadly or stick to what I know?
Dynamic content is extremely powerful. In this section about dynamic writing do you want to keep the section generic about the fact that you can use variables (or whatever they might be called in your markup/language/editor of choice) or do you want it to be specific to AsciiDoc? Or do you want to explore even more?
What's being presented in the AsciiDoc example can be accomplished in other markup languages or tools (and even unstructured FrameMaker has conditional text). I think it's fair to present an AsciiDoc solution, but it should be in its own section outside of the generic information about what you call dynamic writing.
This really raises the question of tool bias (which is totally fine for someone to have -- I have mine) and whether you want this book to be about collaborative DocOps in general or DocOps using a very specific (predetermined) toolset. If it's to be general, which I would encourage, then this section would need some reorganization/rewriting or a number of other examples added, which could get unwieldy (and probably never be exhaustive). If you want the book to have a (very strong) preference for AsciiDoc, then the possible audience is limited. (As I mentioned elsewhere, I'm commenting as I go, so I don't know how many AsciiDoc examples are in the book.)
How far down the dynamic rabbit hole do you want to go? You mention building different doc sets for different audiences, but what if a doc set was built for every individual, which is conceivable with docs being built dynamically based on a user login and account information being used to identify who the reader is and what components they have access to? Such dynamic content and systems exist and should be part of the consideration for a Collaborative DocOps book, in my opinion.
"Tag-based languages like DITA may provide a degree of dynamism " It most certainly does! :) "but for reasons we’ll explore more later, they tend to limit collaboration." Maybe, but maybe not. Because of Lightweight DITA (LwDITA) contributors can create content in XML, HTML, or Markdown making it entirely possible to collaborate or receive content from a large group of people using tools they're familiar with.
Perhaps my point (again) is that DocOps can have a number of different toolchains, and the toolchain that is best for one team may not be the best for another, which should be acknowledged, so that readers can discern what may be best for them.
And that should take readers into issues about how content is going to be reused or repurposed. Will it just be used in docs or will it need to serve other needs, such as chatbots, marketing content, and more? The answer to questions like that determine tools, toolchains, and whether a DLML is sufficient or whether a tag-based language with the necessary metadata is a better fit.