I do agree that this is a useful distinction.
I'd have called how-docs and FYIs "howto", as I think that term would be recognised more clearly, but that's a quibble.
I do agree that this is a useful distinction.
I'd have called how-docs and FYIs "howto", as I think that term would be recognised more clearly, but that's a quibble.
Immutable documentation, at its essence, isn't new. Wikis are in many ways immutable documentation due to the diff. The interesting thing here is trying to organize the "small bits of hard to organize" information around slack. More often, however, the real problem is that we need to properly organize this documentation at the point the organization becomes more evident.
For a tool, that should be obvious: --help should be obvious. It's not true in all cases.
This is a great way to articulate something I've been trying to talk to people about for a while - is this something you've thought of for yourself, or do you know of anywhere that talks about these patterns?
Sure, getting everyone to maintain docs with their features is useful. But given enough time, you'll end up with so many "close but not really close" concepts in documents it's very hard to stay on top of without someone putting some organization into play.