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.
Al Sweigart /
npub138…s88z7
2024-05-22 15:20:53
Author Public Key
npub138afdyyaxs7ta0ugnuf3jt3swxtz83gsywf5grg465w5ktqg7z2qds88z7Published at
2024-05-22 15:20:53Event JSON
{
"id": "c29e03f6264f6978d4ace9acdb900066bab86c929b99135a10ffef36b5ca6d74",
"pubkey": "89fa96909d343cbebf889f13192e30719623c5102393440d15d51d4b2c08f094",
"created_at": 1716391253,
"kind": 1,
"tags": [
[
"proxy",
"https://mastodon.social/users/AlSweigart/statuses/112485417160251077",
"activitypub"
]
],
"content": "Here's one thing I don't like about how software people write documentation:\n\nIf 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.",
"sig": "55cf1e8412466d7875e1bd23e0f26e99a1cd73b7ce8c83f37bd6d725101aa4c6bc2115cd25ecde5512029605533fde128d4d3937df9dbef26cf235cb2ba61904"
}