This is something that’s caught myself out over the years, and I’m sure a lot of other people have done the same. When writing code or documentation, or even an email we leave out details we think are “obvious”. What we don’t think of is our own specialist knowledge - the invisible knowledge we have of our environment, or our context.

These days I work on accounting software, but in addition to my software development degree many years ago I also started an accounting degree using my elective papers. This means I have more knowledge than a lot of new developers. I have to think about whether I’m applying programming or accounting knowledge when writing my comments.

For example, this would be obvious to someone with experience in both fields (in pseudo-code):

public enum DrCr { Debit, Credit }
public class AccountValue { Decimal Value; DrCr Sign }
public AccountValue GetAccountValue(Decimal value, DrCr positive) {
    if (value >= 0) { return AccountValue(value, positive); }
    return AccountValue(-value, positive == Debit ? Credit : Debit);
}

but for someone outside the accounting field this makes no sense - why not just use negative numbers? The reason is that accounting predates the acceptance of negative numbers, and history is hard to change.

I’ll also add a small anecdote I saw printed in the newspaper here a few years ago. Alas this was before online archives, so I can’t link to the source.

A couple was visiting my city from another city in the same country. They were planning to travel out to visit family on the train. In their city there is one rail line, so when they looked at the departures board and saw ‘Stopping at all stations’ they got on that train. Unfortunately we have four lines here, and the didn’t know to check which line they were heading for. A bad design of signage had these two critical pieces of information separated, and since everyone here - or from a city with multiple rail lines - instinctively knows to look for it this was rarely a problem.

Context is everything.