Thread by @lemay

I was intrigued and amused by this thread yesterday about EXAMPLES sections in man pages (or the lack thereof). I have several long-winded, should-be-a-blog-post, ancient-nerd-writer thoughts in thread. 🧵

https://twitter.com/b0rk/status/1427308140916363269

I actually worked on man pages at Sun in the early 90's. Mine were not in the core OS, so nothing I did survives, but I had friends in the OS man page writing group and had a good grasp of how they worked.

This would have been in the BSD-derived era of SunOS, before Solaris and before Linux. I was not around for early Unix, but I learned from people who were.

Historically (in ancient times) the man pages were written by the same person who wrote the original command. In the same way that there is little consistency across the actual commands in how options are named or specified, everyone wrote man pages their own way.

A lot of man pages were super minimal. The only man page I can remember from that time that always had a really good set of examples was tar(1) (with good reason, tar is impossible 🙄).

Also historically man pages were supposed to be reminders for syntax you already know but could not specifically remember. They were not supposed to be learning tools.

I've used the analogy of trying to learn French from a French dictionary before; theoretically possible but not especially easy. It's the same idea. Even if examples were nice-to-have they were not really considered part of the core role of a man page.

Learning-wise there were actual (paper!) user manuals from which you could learn unix--shelves of binders, that's how I learned--or at the feet of more experienced people. O'Reilly started out writing unix manuals as paper books you could actually buy. (I have a bunch, still!)

FORK TO NOTE--> I've seen some replies to the original tweet arguing that man pages are minimal because "no one would want to write extensive documentation in the rudimentary editors of the time." They wrote the entire system in the rudimentary editors of the time!

It wasn't that bad! Arguably documentation is just code with longer lines. :D :D <—END FORK

Even in the 90's when there were actual tech writers working on them (in better editors) there wasn't really anything that one would call content strategy around man pages, no (few?) attempts to make the sections consistent, or to fill in the gaps.

Man pages were written by hand and not structured in any current sense of the term. The writing format was nroff/troff, a tag language that (especially with the man macros) was mostly just for basic typesetting.

In terms of section headers the title, description, and options were required (by convention), and that was just about it. Content strategy: ¯\_(ツ)_/¯

Even at Sun, where they had one of the most comprehensive technical writing groups I've ever worked with (and where I started out), the man page writers were terribly overworked and understaffed.

To get stuff done they prioritized changes to title, description, options, and anything else was usually too low on the list to get done.

I also have the impression that the writers in that group often had a strong sense of historicity, that the original structure and tone of the man page was …not written in stone, per se, but preferable to starting over with new work. FORK TO AMUSING STORY —>

There was a dustup when I was at Sun over the tunefs(8) man page, whose original BSD version had contained the phrase (under BUGS) "You can tune a file system, but you can't tune a fish."

Tech writers, generally speaking, have an aversion to jokes. Jokes often fall flat and translating them into different languages is nearly impossible. (This probably explains why a lot of technical writing is very dull. It's supposed to be like that!)

In Sun's tech writing jokes were really frowned upon, and explicitly banned in the style guide. So a well-meaning tech writer, during the course of editing or updating the tunefs(8) man page, removed that line. And it shipped that way.

The resulting email furor within techwriters@sun when the change was found out went on for a long, long time. (tech writers have an aversion to jokes but are also the most nitpicky people you will ever meet.)

The end result was that the "tune a fish" joke went back into the tunefs(8) man page with a comment indicating that no one should ever, ever remove it again (something about leaving it in "until the time_t runs out", I seem to remember) <— END FORK

You might think that with historicity and with actual trained writers that the improvements that Sun made to the man pages would have survived. Sadly Sun itself switched to the SvR4 (AT&T) version of Unix, abandoned all the BSD work and started over.

(the tunefs joke went away altogether at that point)

And of course Solaris itself eventually faded away and other unices, mostly linux, took over, with a whole other culture of man pages and extra documentation (of which I don't have a lot of experience; see original thread)

To sum up (finally) there really isn't an answer to why man pages don't consistently have EXAMPLE sections. Like most computing history, there was no grand designer, things were just cobbled together ad-hoc over the years with the resources and energy people had at the time.

Man pages and documentation are not exactly any sort of example of the beauty out of chaos that Unix has always had, but they did go along for the ride. - end 🧵-