Speaking of user interface guidelines, developer Matt Sephton and others compiled many of Apple’s human interface guidelines, starting from 1980, all the way to 2014, including some goodies like early drafts, NeXT, Newton, and so on.

Elsewhere, designer Geof Crowl put together his own list that goes broad instead of deep, including style guides other than Apple’s, too.

The list was made in 2020 and a few links are already broken, but there are some gems here like the modern Designing for Playdate, or the classic Zen of Palm from 2003. You can learn a lot just by grabbing one and scanning it.

Let me add a few more I know of:

• Amiga User Interface Style Guide (1991)
• Magic Cap Concepts (1995) with a strange subtitle “Everything right is wrong again”
• Java Look and Feel Design Guidelines (1999)
• Windows Interface Guidelines for Software Design (1995)

Aanand Prasad, Ben Firshman, Carl Tashian, and Eva Parish put together Command Line Interface Guidelines for people who write command-line tools.

I like that it harkens and links back to other writing, and is also pragmatic: shares good parameter-parsing libraries, commonly used options, and so on.

Here are some good principles that caught my attention:

Display output on success, but keep it brief. Traditionally, when nothing is wrong, UNIX commands display no output to the user. This makes sense when they’re being used in scripts, but can make commands appear to be hanging or broken when used by humans. For example, cp will not print anything, even if it takes a long time.

It’s rare that printing nothing at all is the best default behavior, but it’s usually best to err on the side of less.

By default, don’t output information that’s only understandable by the creators of the software. If a piece of output serves only to help you (the developer) understand what your software is doing, it almost certainly shouldn’t be displayed to normal users by default—only in verbose mode.

Catch errors and rewrite them for humans. If you’re expecting an error to happen, catch it and rewrite the error message to be useful. Think of it like a conversation, where the user has done something wrong and the program is guiding them in the right direction. Example: “Can’t write to file.txt. You might need to make it writable by running ‘chmod +w file.txt’.”

Signal-to-noise ratio is crucial. The more irrelevant output you produce, the longer it’s going to take the user to figure out what they did wrong. If your program produces multiple errors of the same type, consider grouping them under a single explanatory header instead of printing many similar-looking lines.

Consider where the user will look first. Put the most important information at the end of the output. The eye will be drawn to red text, so use it intentionally and sparingly.

Make it recoverable. If the program fails for some transient reason (e.g. the internet connection went down), you should be able to hit <up> and <enter> and it should pick up from where it left off.

There’s a lot more inside.

(The document is undated, but I believe the effort started in 2020. It seems to still be updated via GitHub, where you can also send in your suggestions.)