MPS documentation conventions aren't well documented

[rptb1]

This came up as a result of #105 (review)

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.

#141 (comment) 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

mps/code/mpmtypes.h

Lines 29 to 30 in e179634

	typedef unsigned long Sig; /* <design/sig> */
	typedef int Res; /* <design/type#.res> */

. 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 #119 (comment) 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.