Long post, roller coaster of thoughts.
Unsurprisingly, I love Mallard. It captures a lot of what I consider best practices (and a few mistakes) from decades of doing docs and docs tools. It has features to solve problems that still no other format does to this day. It is far more pleasant to write than any other XML format. (I recognize that’s a low bar.)
I like Yelp. It does more under the hood than any other operating system’s help viewer. Its conditional processing is robust and powerful. Some years ago, I did some proof-of-concept work around doing the transforms in JS with Handlebar templates, because nobody else knows XSLT. It’s viable, but I don’t have the bandwidth to see it to completion alone.
None of this matters if nobody is writing docs.
I’m just one person, and my current job doesn’t revolve around docs. Either a group of people have to step into the work, or we have to scale what we do with what we can do. We can’t have our entire docs system be xkcd 2347.
I actually think a lot of app help could be served by something much, much simpler. Find or define a Markdown flavor with the features we will use and can maintain (yes to tables and notes/tips, no to embedded HTML). Render that in something like a GtkTextView. Do it in-process, no extra app. Don’t use web technologies, because that’s a never-ending source of CVEs, and it locks you out of EL distros. There are a lot of features we’d lose, but again, those don’t matter if nobody is writing docs.