Excellent thread, BrowserUK ... very thought-provoking throughout, and showered with up-votes.

I definitely agree with you that POD is too limiting ... except for the fact that it can be, and to the extent that it is, embedded within or alongside the Perl code that it refers to, and therefore also subject to change control.   It is, therefore, a very special purpose form of documentation, and not good enough for the entire system.   (But, one might suggest, really not intended so to be.)

For most documentation purposes, I use the DocBook format (or, in some cases, another proprietary format such as the one you encountered Intel using ...), and the XMLMind XML Editor (XXE) as the writing tool of choice.   (I’ve never purchased the commercial version.)   The documentation is written in XML format, but the tool formats it on-the-fly so that you are seeing it, and writing it, in a WYSIWYG-formatted view.

These are “semantic markup” techniques:   for instance, the definition of a <function> includes subtags (and subtags of these) which describe what the various elements are ... arguments, return values, description, errors thrown ... not how they will look on the page.   From this XML-database, which is always known to conform to the specified schema, information can be selected, extracted, and then formatted into a variety of deliverables, either using (commercial ...) XXE facilities, or third-party XML tools like Saxon.

There are also converters which can scan for and extract POD documentation, although they oblige the POD-writer to adhere to certain “markup” conventions in order to convey usable semantic meaning.