"It's a dangerous thing to mistake speaking without thought for speaking the truth." Fan of #crows, #StarTrek and the #Japanese language, among many other things. Currently posting one frog species per day. If I keep this up, I should be done in about 20 years. My toots are searchable.
Here's one thing I don't like about how software people write documentation:
If A is a type of X and B is a type of X, there's a preference to separate X into its own definition elsewhere (like deduplicating code by putting it in a function). But this means the explanation of A or B is incomplete, because you have to click to learn what X is. If X is a type of Y, now you have to click again to figure out Y. You just wanted to learn what B was, but now you have to learn everything.
@AlSweigart Technical writer here. You should really look into DITA and the principles of content reuse (rather than content cross-reference). Check out the book The DITA Style Guide, which you can find for free online.