PSA: When writing documentation for a terminal command or anything with a rigid syntax, always include fully spelt-out examples (i.e. examples that you could directly copypaste and they would run, if the context were right).
Say you're writing a multi-user CLI todo list application and documenting the function "add-item". Then this:
$ add-item <item> --user <user> --priority PRIORITY
is not a (fully spelt-out) example, because it's not runnable as is. As a consequence, as a user, I can't apply it without sorting out a couple questions first: is "<>" part of the command syntax, or is it just here to denote the fact that users should substitute a string? What about the caps?
To contrast, here's a fully spelt-out example:
$ add-item get-groceries --user alex --priority 3
This might not be copypastable as is, of course, because chances are there's no user named "alex" in your setup, but it's as close as possible: if your setup did have the user "alex", the command would work.
(note that even though, say, `add-item item` would also technically work, it's not ideal, because "item" might be either a fixed keyword, or a free string, so users don't know whether they're allowed to put in another string in that slot. Prefer examples that are as real-lifey and specific as possible, like `add-item get-groceries`)
If your examples are not fully spelt-out, they're not examples, they're specification, and you're assuming that users know the specification syntax.
Grégoire Locqueville
npub1mg…94dr4
2026-01-05 13:11:34 UTC
Author Public Key
npub1mghlhx2z6vnmvhhxdu2j66dyylc3ff9y9a56fkdc32uu4wtr8xust94dr4Published at
2026-01-05 13:11:34 UTCEvent JSON
{
"id": "92f16b328764eb4e64f0786fde5ddabed28611fc3ff703a6fcbf04da61135b8d",
"pubkey": "da2ffb9942d327b65ee66f152d69a427f114a4a42f69a4d9b88ab9cab96339b9",
"created_at": 1767618694,
"kind": 1,
"tags": [
[
"proxy",
"https://mathstodon.xyz/users/glocq/statuses/115842658783104180",
"activitypub"
],
[
"client",
"Mostr",
"31990:6be38f8c63df7dbf84db7ec4a6e6fbbd8d19dca3b980efad18585c46f04b26f9:mostr",
"wss://relay.ditto.pub"
]
],
"content": "PSA: When writing documentation for a terminal command or anything with a rigid syntax, always include fully spelt-out examples (i.e. examples that you could directly copypaste and they would run, if the context were right).\n\nSay you're writing a multi-user CLI todo list application and documenting the function \"add-item\". Then this:\n\n$ add-item \u003citem\u003e --user \u003cuser\u003e --priority PRIORITY\n\nis not a (fully spelt-out) example, because it's not runnable as is. As a consequence, as a user, I can't apply it without sorting out a couple questions first: is \"\u003c\u003e\" part of the command syntax, or is it just here to denote the fact that users should substitute a string? What about the caps?\n\nTo contrast, here's a fully spelt-out example:\n\n$ add-item get-groceries --user alex --priority 3\n\nThis might not be copypastable as is, of course, because chances are there's no user named \"alex\" in your setup, but it's as close as possible: if your setup did have the user \"alex\", the command would work.\n\n(note that even though, say, `add-item item` would also technically work, it's not ideal, because \"item\" might be either a fixed keyword, or a free string, so users don't know whether they're allowed to put in another string in that slot. Prefer examples that are as real-lifey and specific as possible, like `add-item get-groceries`)\n\nIf your examples are not fully spelt-out, they're not examples, they're specification, and you're assuming that users know the specification syntax.",
"sig": "6195ddd0cb7c368f21070be4be3b08078fba62e833e7d5e68722d1bd9b3c7c221d0d55665f38d408d72f0841e90bea6ac28aa25c8e0b01583ccb7d284efdd1e9"
}