When written well, manpages are an awesome form of reference documentation.

That often doesn't happen, though.

(Manpages do not need installation instructions or the full changelog for the program. They do need examples, including the simplest possible way to use the program.)

This reminds me, I've not taught anyone how to write manpages in years. Maybe I should? is hopefully still reasonably accurate.

Show thread

@liw My pet manpage peeve is not listing all the options in tabular form, instead forcing users to read through pages of prose hoping for a casual mention of the flag they are looking for.

@liw it gets worse in large companies' internal tooling too :(

People seem to keep forgetting the lessons from Unix

@liw This so much! I usually glance at the args and then skip down to the examples.

Sign in to participate in the conversation

Lars and friends