search

abathur / ldmud-doc

A temporary repo for working on a revamp of the documentation system for http://github.com/ldmud/ldmud
0 stars 0 forks source link

clearly defined document "status" headers (OPTIONAL, etc.) #11

Closed abathur closed 7 years ago

abathur commented 8 years ago

The docs use a number of status headers to convey either the state of the doc/concept or the code it's documenting; I think this list is comprehensive or close: OPTIONAL, PRELIMINARY, EXPERIMENTAL, DEPRECATED, OBSOLETE. Some things in /obsolete/ also use a line like "REMOVED EFUN" or "REMOVED MASTER APPLY", so we could say there's an implied "REMOVED" on the list as well.

I'd like to have the shortest possible list, and make sure these statuses are unambiguous. I can split hairs and imagine some distinctions between these, but I can also make a case that the differences between preliminary/experimental and obsolete/deprecated/removed aren't painfully clear.

abathur commented 7 years ago

Just going with personal preference to remove the least-clear labels and only use:

abathur commented 7 years ago

For that matter, I would greatly prefer being able to cut "removed", actually delete outdated docs, and integrate any essential historical concepts into "obsolete" admonitions in the appropriate contemporary doc.