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/

> "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.

> My jokes aren't funny and are actively confusing.

Well, I found that sentence in the post was very funny ;-)

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].

[1] https://en.wikipedia.org/wiki/Literate_programming

[2] https://github.com/spicyjpeg/ps1-bare-metal

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".