MPS documentation conventions aren't well documented

[rptb1]

This came up as a result of https://github.com/Ravenbrook/mps/pull/105#pullrequestreview-1279762207

This issue was created as a place to collect things that we might eventually turn into a guide or other docs.

Here are a couple to start with.

1. What is the "document history" for and when to update it.
2. What on earth are tags?

[rptb1]

2. What on earth are tags?

Quoting notes from my journal, dated 2023-01-11:

Talking to PNJ, I possibly came up with the best explanation.

Tags (like design.mps.splay) are a way to extend English vocabulary with specific concepts with a precise meaning, so they can be referenced unambigously. They are a precise jargon (the specialized language of a group).

Without tags, people will tend to say things like "the design" or "splay trees" or if more precise "the design of our splay trees" or even "the documentation of our design of splay trees" but these phrases tend to get misinterpreted, change, and are hard to track down.

Tags aren't defined by their automation, but by their resistance to corruption in the face of changing automation. In some ways, they're defined by being able to be found. You can grep for them. Tags have survived TXT files, paper printouts, Lotus Notes databases, XHTML, reStructuredText, and they're still present and useful.

For this reason, they have a syntax (a.b.c) so that they can be recognized, and a context (the project), and little else. Conventions have sprung up for the components of a tag that help with finding them (e.g. "design.mps.splay" is probably a document in the repo in design/splay.txt) but that's not an essential part of what they are.

They are an implementation of rule.generic.once, which I decline to define here.

PNJ asks "must a tag be unique". Well, if we are implementing rule.generic.once using tags, then there should be one place where the tag is associated with a definition, and all other places it's a reference. That is what we do in the MPS.

There are specific details about how we've implemented tagging in the MPS. For example, in design documents, in the manual, in code, etc. It's a good thing to stick to certain conventions so that they can be found. We should describe those. [Local tags, relative tags, etc.]

Conceptually, you could replace every tag with a UUID. But that bad for human brains. Conceptually, you could replace every word in English with a UUID too.

See also book.gilb88.tar-principle <https://info.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo/mminfo/book/gilb88/tag-principle>_:

Untagged ideas never die, but they do just fade away.

Tags are like URNs. Links are like URLs.

[rptb1]

Conventions for FIXME, TODO, NOTE, etc.

https://github.com/Ravenbrook/mps/pull/141#issuecomment-1433253292 says:

"TODOs" are for nice-level stuff.

[rptb1]

Tag references in source code are a bit messy. At some point in 2002 we had the idea that we'd use HTML-based tagging, so tag references started looking like this https://github.com/Ravenbrook/mps/blob/e179634de028b2db090ee6a2358391155102b74f/code/mpmtypes.h#L29-L30 . In hindsight this wasn't durable. We might want to undo it. In any case, it needs documenting.

[rptb1]

We have design.mps.doc ("Documentation") that outlines requirements for documentation, gives a brief overview of design choices, then is more like a guide for writing it and rules for formatting. This could be expanded / split.

[rptb1]

Conventions for FIXME, TODO, NOTE, etc.

On this topic, see https://github.com/Ravenbrook/mps/pull/119#discussion_r1115554660 which says:

TODOs especially need to be comprehensible to people who come across them without deep knowledge of the thing they annotate. Form part of the doc describing how to use TODOs.

... and a rule.

[rptb1]

The meaning of the date at the top of a document is not obvious, and makes documents appear out of date, even if they are maintained.