how document/code "status" is handled

A number of existing docs use the first line to declare a status of some sort (generally: optional, preliminary/experimental, and deprecated/obsolete/removed). Additionally, everything in the "obsolete" directory has a sort of implicit status which is hard to untangle from the OBSOLETE line. Going over these docs has exposed some weirdness and contradiction to me that suggests we should maybe rethink how status is conveyed.

Here's a short list of some of the smells/weirdness that make me think there are underlying conceptual problems:

As I read the existence of OBSOLETE, DEPRECATED and REMOVED status lines, I assume obsolete means something that hasn't yet been officially deprecated, but shouldn't be used (see efun/md5 for an example). The README doc states that the obsolete directory contains "docs for features removed from the driver," however, which implies that OBSOLETE and REMOVED could also be equivalent.
There's a copy of parse_command in obsolete/ and another in efun/, because the function is "removed" in compat mode only. The documents are near-identical, but ripe for divergence. The obsolete copy doesn't have an OPTIONAL status, but the one in efun does. The copy in "obsolete" breaks all conventions by putting "Compat mode" and a blank line at the top of its synopsis section. What does this mean? It implies this synopsis is FOR compat mode, but the history section of both documents state it is REMOVED from compat mode. I could also interpret as meaning older versions which supported this function in compat mode used these function forms, but the forms are equivalent between both copies.
Anything in /obsolete/* which is marked with an OPTIONAL status has really murky semantics. The README states that obsolete contains "docs for features removed from the driver", but the alist efuns (insert_alist, intersect_alist, order_alist) all have an OPTIONAL status. These contradictions make it very unclear whether they were optional in their past life and are now removed, or whether they aren't technically removed and have instead just been made optional (and might be better thought of as deprecated?)
In the context of a generated documentation system with conveniences like an index, multiple slightly-differing copies of the same document can result in an index with multiple copies of the same function/concept with no clear way to tell which is which (without reading URLs).

I'll follow up with my first take on what we could do with these (eventually), but I'm also hesitant to guide the discussion too heavily at the start, since I realize I may not be able to see the forest for the trees at the moment.

This issue is related to some others:

what statuses do we use/care about and how do we define them? #11
how should status be presented visually (in HTML and plaintext output) #12

abathur / ldmud-doc

how document/code "status" is handled #10