alt Hacker News> My jokes aren't funny and are actively confusing.
I used to write technical documents in prose style, sometimes with meandering stories. I guess I picked it up from my early blogging days. I realized I hated reading some of them back. So I tried to keep it cut and dried. I do sometimes sprinkle a bit of colorful wording just to add a bit of humanity but only if it doesn't get in the way of the main message.
Replies
> "They were the ones who caught the mistakes that no spell chequer could."
I thought that maybe "spell chequer" was the valid British term, which would be interesting, so I searched but it isn't. It turns out that the joke here is that "chequer" is a valid British word, so a word-based spell checker won't flag "spell chequer", so it's self-referential. I see why people found his jokes actively confusing.
When deciding on a style for documentation, I typically draw the line between tutorials and references. The linear top-down flow of an introductory guide lends itself well to inserting additional context throughout it even if not completely on-topic, while in an API or hardware reference you generally want to keep each section reasonably self-contained, trivially searchable for (minimizing false hits by carefully choosing keywords) and readable independently of the others. I have found the literate programming approach [1] of writing entire tutorials as code to work pretty well for this purpose, which I've used to great effect in some of my pet projects [2].
> My jokes aren't funny and are actively confusing.
Well, I found that sentence in the post was very funny ;-)
isnt this what footnotes are for?
Being short and concise is usually the better way.
I tend to be too verbose in writing as I want to explain the context in more detail, but short, accurate, concise is best. Many developers fail at that too, though. Many projects do not have working examples. That annoys me the most. It sends a message of "I don't care about new users learning how to use my project".
I'm glad the author mentioned this particular learning. Even if you do enjoy reading your own jokes, many other people will find them at best annoying and at worst confusing. When you add in people from other language/culture backgrounds the risk/reward of jokes gets even worse!
There was a famous conflict over rms's joke about the abort() function in the glibc manual[0], which said:
> Proposed Federal censorship regulations may prohibit us from giving you information about the possibility of calling this function. We would be required to say that this is not an acceptable way of terminating a program.
I think that joke illustrates nicely what I mean: it would only have made sense to people in USA, and would have just confused others. Even those who understood it would - IMHO - most likely not appreciate it being in the glibc manual. People don't read manuals to be entertained - they read them to find out as quickly as possible how to get their work done.
[0] https://lwn.net/Articles/770966/