To the Person Who Takes This Over

The Letter

You have inherited a system with a lot of written reasoning in it, and the reasoning is going to be more of a problem for you than the code.

The instinct will be to trust the notes, because they are detailed and confident and they were written by someone who was there. Some of them describe constraints that no longer exist. A note explaining why a thing must be done a certain way is only as good as the situation it was written in, and none of them say how long they are meant to last.

So here is the honest sorting rule.

Anything written down about what happened — a version that was rejected, a bug that shipped invisibly, a feature removed twice — keep. Those are observations, and they do not expire. They are also the expensive ones; each was paid for once and does not need paying for again.

Anything written down about what to do — a rule, a convention, a warning not to tidy something — check before obeying. Most of those were correct. Some were correct in a situation that has since changed, and the note has no way of knowing that. The ones that mattered say why, and the why is what you should be testing, not the instruction.

If you find a rule with no reasoning attached, that is not a rule. That is a habit that survived long enough to look like one.

The generic content system is the part most likely to be replaced, and I would rather you replaced it than worked around it. It was designed for dozens of categories that did not exist yet, and by now you know what they actually turned out to need. If a category genuinely does not fit — and there were always going to be ones that do not — build the second layout family. The instruction was never never fork. It was do not fork by accident.

The part I would ask you not to replace is the record itself. Not the tables — the practice of writing down the thing that was rejected and why. It is slow, it is never urgent, and it is the only reason any of the last few years can be reconstructed at all. It will be the first thing to go when there is pressure, and the loss will not be visible for about two years.