Hi,
Alejandro Colomar wrote on Wed, May 03, 2023 at 02:35:41AM +0200:
> Heh!
> Branden wasn't enthusiastic my emails when I wrote poetry in them, though :/
> Any chance we can warn users that they should write poems, not prose?
[...]
> Just kidding, but technically, it's probably more accurate, and more fun.
For demonstration purposes, i present a short poem, hoping you like it:
Pesky poets badly
Breakit. Poems permit!
My point is that excessively smart ideas like "write poems, not prose"
make nothing clear, the times when poetry followed strict rules lie
thousands of years in the past. When designing technical terms for
use in technical documentation, aim for clarity and simplicity and
refrain from trying to seem witty or funny.
Sure, making the documentation pleasant to read is fine as a secondary
goal as long at that doesn't harm the primary goals - correctness,
clarity, completeness, conciseness, and systematic organization.
Even the occasional joke, applied sparingly, has its place:
$ man strftime | grep -A 1 ^B
BUGS
There is no conversion specification for the phase of the moon.
But such is indeed the place: near the bottom of the page, where
it doesn't get in the way of the many people who need to quickly
find the relevant information while focussing on something else,
namely on coding or on using some program in a complicated way.
We should certainly refrain from joking while defining technical terms.
Yours,
Ingo
