limiting the nouns we use for notes/caveats/admonitions, and defining clear semantics for them

[abathur]

This is obliquely related to #4, but we've got a large number of these in use at the moment (bug, bugs, note, notes, miscellaneous, limitations, remarks, tips, warning). By default, sphinx/docutils have baked-in semantic support for: attention, caution, danger, error, hint, important, note, tip, and warning. You can also use a generic "admonition" which you can self-title.

We aren't bound by what they use; just providing the background. I think a good heuristic is: let's add as many of these as we can, as long as:

1. the new noun adds a semantic distinction that is meaningful to both doc producers and consumers
2. it can be clearly described/defined in such a way that it clearly doesn't include or significantly overlap existing distinctions
3. it is painfully obvious whether any given "admonition" text should use this noun or not

The lazy/minimalist way to do this is to collapse them all into "note". It's semantically bland, but it's always obvious what to put where. A bad way to do this is including both "attention" and "important" or "hint" and "tip" on our list; large overlaps like this will waste my time when I'm trying to decide which way to push existing admonitions without providing any useful semantic benefit to either us or consumers of the docs; they also make it harder to search for in the final documentation, trickier to apply custom styling later in the HTML/plaintext if we want to make certain types of admonition stand out more, etc.

I don't have my own concrete recommendations yet because I haven't burned too much time actually thinking about these distinctions myself; categorizations like this are my Achilles' heel and I'll resist doing them as long as I can. :)

[zesstra]

I believe we could collapse it into the existing admonitions? We probably need only error, hint, attention, warning, danger plus note as general catch-all for the rest. I don't really see the need to invent a bunch of our own or combine them all into notes?

[abathur]

@zesstra Not sure there's a need, just making it clear for discussion purposes that we don't have to follow their semantics (and that theirs may not be worth following) if we have ideas that fit our use case better, and it's relatively simple to make a new one of these that works just like the others but has a different name.

To be more concrete, we could decide we want a .. crash:: directive that only gets used for admonitions about operations that can cause the driver to crash.

From my perspective, the most important result is a set of clear definitions for what types of note should use which admonition type. When it comes time to build the RST -> Doxygen converter, having well-defined categories that were easy to apply will make it easier to decide how to translate those notes into Doxygen's idioms/commands, and have confidence that it won't produce absurd results on the other end.

[abathur]

@zesstra to be more explicit, it's not immediately clear to me how to decide unambiguously what belongs in error vs warning vs danger, nor note, hint, and attention, nor entirely attention vs warning.

I went ahead and pulled together a census of these at https://github.com/abathur/ldmud-doc/wiki/admonitions and I will try the mailing list as a way to sort out this specific problem.

[abathur]

Per the email I sent, my current preference is:

• note
  • warning
  • security
  • limit
  • stability
  • obsolete
  • misleading
  • tip

Here's how I stake out what those mean:

• note: information needing additional emphasis
• warning: details some potential negative consequence
• security: details some threat to game or system security
• limit: details limitations of the driver, system or dependencies and how they may affect results
• stability: details some performance/crash risk
• obsolete: details some obsolete practice and a better/modern approach
• misleading: discusses some shortcoming in the documentation itself (incomplete/dated/difficult/superficial/incorrect)
• tip: suggests practical/alternative/improved ways to accomplish common tasks, less-obvious alternative uses, etc.

[abathur]

Calling this decided, and I've implemented these. Will reopen if new feedback comes in.