
How to Design Software Good - davisr
https://www.haiku-os.org/docs/HIG/index.xml
======
nayuki
I saw a quick flash of unstyled content (in Firefox) where all the text was
jammed into one paragraph with no breaks. And then the page rendered normally.

So I glanced at the source code, and it surprised me to see that it was not a
typical HTML document, but instead an XML document with a stylesheet. It is
very rare to see a non-HTML page on the web, whether it is the XHTML
serialization of HTML, or fully custom XML.

~~~
mafro
Once upon a time, the whole internet was going to be built this way!

~~~
bjoli
I still think client side XSLT is a good thing. I write simple documents and
it is automatically converted client side. The world's best static site
generator.

I gives me the best of two worlds: simple markup with complete control of
output and CSS styling and instant changes of all documents without a
compilation step.

~~~
dionidium
XSLT got an unfair shake. Yes, XML is ugly, and verbose, and painful to write
code in, but the _ideas_ were very good. Most users never understood the
processing model or the declarative/functional nature of XSLT, and so tried to
write procedural code with it, with predictably nasty outcomes (hint: _<
xsl:if>_ is almost always a code smell). But those who did _get it_ , could
use it to write some pretty elegant little programs.

------
olooney
Wow, this is more like a master class on GUI application design than the usual
guidelines you see. I don't see a byline but someone poured a lot of love and
wisdom into this.

~~~
waddlesplash
Seems the DocBook XML styler broke; there is a byline in the original source:
[https://github.com/haiku/haiku/blob/master/docs/interface_gu...](https://github.com/haiku/haiku/blob/master/docs/interface_guidelines/index.xml#L13)

DarkWyrm hasn't been active on Haiku for some years now (though I think he has
an occasionally-updated Twitter account?), so it's a community-maintained
document at this point.

------
emmelaich
> Good Software Does Not Expose Its Implementation

Excellent goal but way harder than people think. I would say it is not
possible in the fullest.

~~~
fao_
I kind of feel that you just read the title here. It's not talking about the
'fullest':

    
    
      An example of this would be if a music composition
      program has an easily-reached maximum song size because
      the code monkey who wrote it used a 16-bit variable
      instead of a 32-bit one. *While there are sometimes
      limitations that cannot be overcome*, the actual code
      written and the architecture used when it was written
      should have as little effect as possible on what the user
      sees and works with when using your software.
    

(emphasis mine)

I think it might be better rephrased as:

1) Don't add unnecessary constraints (or: Don't prioritise efficiency/etc.
over the interface).

and

2) A good interface abstracts away technical problems, rather than presenting
them in a different form.

~~~
bkmartin
The most common example I see is the password requirement that it must be
between 8 and 16 characters... The 16 character limit is the main issue
there... You know it has to do with the wya the data is stored.

~~~
adrianN
Between 8 and 16 characters, but only 7 bit ASCII. But there is no error
message if you use § in your password, it just kills the server.

------
ASpring
Looks like most of this is derivative of Molich and Nielsen's heuristic
evaluation of user interfaces guidelines from 1990.
[https://dl.acm.org/citation.cfm?id=77486](https://dl.acm.org/citation.cfm?id=77486)

------
doubletgl
Sorry to be a pedant, but the grammar and capitalization in this guide do not
instill confidence. "How to Design Software Good" <\- design well? "How will
Your Users Do Their Work?" <\- Seriously?

~~~
Antoninus
Maybe its meant to be tongue-in-cheek.

~~~
heidar
I thought it was a vague zoolander reference.

~~~
lucideer
This is also what I assumed, and I'm fairly sure it is.

Especially since the grammar in the article is relatively OK, whereas that
title would be really terrible if it were not a pop-culture reference.

------
davisr
I feel these conventions, while written about HaikuOS, apply equally to all
domains of software authorship.

~~~
yoz-y
Indeed, a lot of these conventions are part of most of the platforms' Human
Interface Guidelines.

------
bo1024
I want to mention the classic book "The Design of Everyday Things" which
shares a lot of points with this post, though not about software at all.

~~~
war1025
I read this book a few years ago and was really disappointed by the content.
Apparently the version I read was the "revised and expanded edition", so maybe
it just got worse with the update...

~~~
rofo1
OT, but you are not alone - I also thought it wasn't that good as it was
claimed. I've seen it recommended many times on HN.. I can't understand why.
Now when I read the title, I immediately think of doors and handles.

------
rlanday
> Haiku is an operating system which is known for its speed and being easy for
> anyone to use.

That's a fairly bold claim. Haiku is an OS that basically no one uses for any
purpose. Why should I take any sort of design advice from them?

~~~
waddlesplash
Being "known for its speed and ease of use" and "very low user base" are ...
not mutually exclusive in the slightest, so I fail to see how your comment has
relevance?

By your logic, since macOS has ~1/10 the install base of Windows, clearly this
means that "very few" people use it and we should not take Apple's advice on
anything design-related.

~~~
oralty
>> Haiku is an OS that basically no one uses for any purpose.

> By your logic, since macOS has ~1/10 the install base of Windows,

Does not follow. MacOS use relative to Windows is not at all a fair
comparison. Firstly "everybody" uses Windows, so 1/10 of huge number is still
a huge number. Second, except for gaming and some particular areas like EDA,
MacOS has a general software library with a broad-base of technical and non-
technical users throughout the world. Haiku OS cannot claim to have anything
like that.

~~~
waddlesplash
> MacOS has a general software library with a broad-base of technical and non-
> technical users throughout the world. Haiku OS cannot claim to have anything
> like that.

That was the second half of my comment. Please re-read the first half.

My point in that part, though, was that macOS has ~1/10 the users of Windows,
but Windows' UI/UX was/is widely regarded as absolutely atrocious, and macOS'
as being pretty good to great, depending on who you ask. So "if it has less
users, their thoughts on design are irrelevant" is ... not a good argument.

~~~
pooppaint
I reread and it didn’t make any difference. MacOS may have 1/10 the Windows
base but that is not having “very low userbase”, while I think it is quite
reasonable to say that about Haiku. Reread what I said, the MacOS base is
large and it is a _general_ base of highly technical and non-technical users
alike that are not all hobbyists. This does not describe Haiku in the
slightest.

There is a valid point to be made about verifying usability and the need for a
large and diverse userbase.

How much you want to bet that the Haiku userbase is overwhelmingly male? And
this is not to make some concerned sexism argument but to illustrate that the
community is more representative of the IT crowd rather than the general
population.

~~~
waddlesplash
> There is a valid point to be made about verifying usability and the need for
> a large and diverse userbase.

OK, that is indeed a valid point, but not one I got from the first comments.

I think Haiku has a diverse enough following that we are past most of these
concerns, and a lot of our major paradigms which differ from other OSes were
validated in the BeOS days. There are some areas where we still have work to
do -- e.g. interfaces for the blind -- but overall we are doing quite well.

> How much you want to bet that the Haiku userbase is overwhelmingly male? And
> this is not to make some concerned sexism argument but to illustrate that
> the community is more representative of the IT crowd rather than the general
> population.

Oh, I know it's true of Haiku, but I practically can guarantee the same is
true of Linux/BSD/etc. So then, can only "mainstream" operating systems have
anything to say here?

------
rwmj
Slightly off topic, but has anyone tried Haiku?

We recently ported nbdkit to Haiku and it was a pleasant experience dealing
with the developer. However I never actually _used_ Haiku (just reviewed and
applied patches).

~~~
Crestwave
I have. It was a joy to use; fast, cohesive but familiar due to partial POSIX
compatibility, inspiration from other operating systems and a GNU command-line
environment, with object-oriented design and unique concepts. One of which is
its package manager, which installs into a filesystem image that is mounted
read-only to ensure the files are incorruptible.

------
lostgame
I absolutely love long articles like this. This is full of brilliant
information. Fantastic.

------
jrockway
I am not sure I agree with all of this. I worry that the article encourages
you to dumb-down software so that your users feel completely helpless. That is
the opposite of what you should do. Your users should feel enabled and
encouraged to explore and experiment. Sometimes they may encounter jargon, but
if it ultimately helps them gain a better understanding if they choose to
research it more, I think it's helpful. There is a difference between saying
"the file is corrupted, and there is nothing you can do" and "the file is
corrupted, and you are too dumb to fix it so there is nothing you can do".
Omitting details in the error forces users into the second class; even if most
users are unwilling to google for a solution, you need not remove their
ability to do so. (And in fact, most of these cases are the developers
projecting -- the problem is not that the user did something wrong, but that
the programmer messed up the implementation. Why should a file be corrupted
when reed solomon codes exist? Very rarely have I seen a case where something
was so damaged that it could not be recovered; rather, the engineers chose not
to design in proper error recovery. Then they blame the user for a disk sector
going bad when the engineers know full well that disk sectors can go bad.)

The other thing I think I agree with is the philosophy on designing
complicated operations. Every operation a user performs should leave them with
no question as to what the outcome will be when they click the Big Red Button.
And they should be able to painlessly undo it. Imagine typing without a
backspace key. Your words per minute would be near-zero because of the fear of
making a mistake. Undo is essential.

The lack of transparency around state changes is something that makes users
hate software. Who will this share button share with? What does "make my
YouTube comment publicly accessible" actually mean? Users don't know, then
they make the wrong decision based on incorrect information, and get mad --
and rightfully so. We blame the user, but it's our fault for laying hidden
traps. You can implement social media without tricking users, but we choose
not to.

I see a lot of people fall into the "great is the enemy of good" trap with
regards to undo. They see some operation that creates some immutable effect on
the Universe, so the only remedy offered to the user is "email the dev team
and we'll try and fix it." This is a pain for the dev team and a pain for the
user. Yes, there are certainly permanent changes that software can make. Send
an email, launch the nukes. But those should not be barriers to letting users
undo. If they want to undo something that sent an email, you'll just have to
send another email apologizing. That is all the development team is going to
do when they have to manually fix it. Nukes can be killed while they're in
flight; better to have some fallout near the launch site than to start World
War III. And yet, we consistently fail to offer undo in most applications, so
users learn to be very scared of doing anything, and that fear prevents them
from accomplishing their goals. That's our fault, not the user's.

I have seen this all in action at work. We have something that is a "big red
button" (we're an ISP, it's the "change service plan" button). People will not
click this, and it's because they don't know what it will do. If we said
"clicking this will cause the customer to pay $x a month, with the next
invoice being sent on 12/01 (click here to see a preview), and their bandwidth
profile will be set to XMbps in the next 30 seconds", then people would click
the button, because they know it will solve their problem, rather than create
a problem.

Anyway, you have to give your users understanding and the ability to safely
experiment (which is how you gain understanding). That is what makes software
a tool to enhance productivity, rather than an annoyance that makes the user
do extra work. Just dumbing down your error messages isn't going to cut it.

~~~
JadeNB
> We blame the user, but it's our fault for laying hidden traps. You can
> implement social media without tricking users, but we choose not to.

Aside from the fact that it's a minefield of dark patterns, how did social
media get into this discussion?

~~~
fao_
> Aside from the fact that it's a minefield of dark patterns, how did social
> media get into this discussion?

"Aside from [the thing that makes it relevant to this discussion], how is [x]
relevant to this discussion?".

~~~
JadeNB
The layout of casinos is also a minefield of dark patterns, but I'd have been
surprised to see it crop up in the middle of that comment without explanation
or follow-up.

------
vitornovictor
A great talk on the topic - John Ousterhout: "A Philosophy of Software
Design": [https://youtu.be/bmSAYlu0NcY](https://youtu.be/bmSAYlu0NcY)

------
nixpulvis
Given:

> Good Software Uses Everyday Language

I'm curious why keyboard shortcuts are called accelerators.

Overall looks like a pretty good set of things to think about as a UX
designer.

~~~
Narishma
That's what keyboard shortcuts were called in some systems like BeOS, early
Windows and probably others. I would guess it's because they provide faster
access to a feature or function than going through menus.

------
qwerty456127
> depend only on the formats installed by default in the system.

Funny fact I've actually "invented" this philosophy (drivers for every file
format being installed, managed and exposed to applications and scripts by an
OS) when I was a child. I was amazed to see somebody has actually went
implementing this idea (as far as I understand it works approximately this way
in Haiku)

> As an aside, MP3 is a format which requires licensing for decoding and
> encoding to be legal,so depending on the MP3 format is not a good idea
> unless your program deals specifically with it.

This is not true, the patent has expired AFAIK and every desktop Linux
distribution can play it out-of-the box for quite a long time already (and
even if it would not have, people living in countries that don't have software
patenting should be let to make use of their advantage). In fact MP3 is a
great format to depend on as this is the only lossy audio compression format
that really plays everywhere. AAC is better and can be played on the majority
of modern devices and OSes but still not really everywhere, OPUS is the best
but there still are so many devices and apps that don't support it
unfortunately.

~~~
waddlesplash
> as far as I understand it works approximately this way in Haiku

Yep, it is indeed. You can of course write your own translators for custom
file formats and install them along with your application; but then anything
which already handled whatever representation they produced (e.g. PNG/JPG/etc.
images -> BBitmap, Haiku's image buffer class) could then handle those
filetypes also.

> This is not true, the patent has expired AFAIK

Only last year, and this document was mostly written a decade ago :)

Haiku can now play MP3 out of the box also (and since the servers and
buildbots are mostly in Germany, we don't really pay much attention to U.S.
patents anyway at this point.)

~~~
robotresearcher
Some in Germany do. For example the owners of the aforementioned mp3 patent.

[https://www.iis.fraunhofer.de/en/ff/amm/prod/audiocodec/audi...](https://www.iis.fraunhofer.de/en/ff/amm/prod/audiocodec/audiocodecs/mp3.html)

------
cronix
With a title like that, at least it wasn't an article about "How to Speak
English Good"

~~~
stevenhuang
The title's intended, it's meant to poke fun and be light hearted.

------
CathyWest
> Writing good software can be hard, but it is worth the time and effort.

Is it? I want this to be true because I want to write good software. But I've
worked with some very senior developers who would disregard all software
engineering and user experience concerns and just spew large quantities of
low-quality code that made the managers just as happy, especially since it got
done quickly. And the end-users in many niche industries are used to being
shipped garbage, so they're just as happy too.

~~~
xgbi
Disclosure: small-ish company (~100 employees) in France

You know, I kind of went through the same questioning: at my current company
we have an employee that has his niche/historical role on one of the key
infrastructure of our product.

The guys works from his home and whatever hours, commits 300+ lines per commit
(90% of which is unrelated to the commit name, just commenting things or
uncommenting others). The code is a spagetti of if else if else, it has
monstruous "client specific" code (like: if the current client is this guy,
then do that, otherwise for all other clients do this).

There's even a load of "if the program runs in test, answer what the test
expects, otherwise in prod send something else".

Every time I look at the commit tree (a balance of wanting to have fun and
wanting to see what is going on), I'm in horror. The guy __rewrote __the
java.lang.string, the java.lang.date, and some other base classe of the
language to incorporate his own version of the Date handling.

Fun fact, at one point his date parsing code "wasn't happy with october"...
why? because October contains the letter 'T', and he botched his ISO date
parsing (format: YYYY-MM-DDTHH:mm:ss) by checking the presense of the letter
T..

I have many many stories of him commiting some bad code, only to spend 12h in
a row trying frantically to correct the bug by adding ifs and elses.

The last time I looked at his code, he was __rewriting __a huffman compression
algorithm by himself (NIH syndrome) to compress his on disk data. Complete
with loads of code to handle per-bit operations that he wrote b y himself
instead of relying on a battle-proof library.

Management-wise, they accept his behavior because this guy, working from his
own home, often can work at scandalous hours and be on the bridge when he
pushes a botched version to production at 2AM. At the time of this comment,
his last 4 commits on master are at the following time: 08:57PM, 10:40PM,
12:11PM, 01:02AM

I know I'm venting hard, but this guy is probably be the best paid engineer of
the company, he is a huge liability IMO, and is present at all-hands meeting
maybe once a month. So yeah, why bother coding great code, making sure that
your tests and CI are green, when some other guy with a bit more history in
the company can get away with doing shitty work and having poor life balance,
as long as he shows "commitment" when he botches his software releases.

This is really some life-long questioning of mine: should I care about things
or should I focus on politics and disregard others. Aren't those on top of the
pyramid the more "sharky" people that climbed the ladder not by pure skill but
by showing the appropriate (bad) behavior when needed and correctly
compartimentalized their own questions about ethics and got away ?

~~~
lucio
I bet the cost/benefit for the company is positive, and as long the clients
are happy and paying, how this guy works is irrelevant. he was rewriting a
huffman compression algorithm by himself because he's bored and he wants to
learn and experiment. I bet is not a good life he's living. There's a great
disorder in working from your home at odd hours, it's not healthy. He would be
happier working normal, fixed hours, and with a manager to guide him.

~~~
philangist
> There's a great disorder in working from your home at odd hours, it's not
> healthy

I'd be curious in hearing you elaborate on this. I've been in a WFH setup like
this for about 4 months, and while I enjoy it right now I do wonder if it'll
be something I might regret after 2-3 years on this schedule.

My primary reasons for working like this are that: 1\. I hate being in the
corporate office environment, it feels very artificial and constraining 2\. I
tend to have my most productive coding sessions very late at night anyway

~~~
kool_moe_d
I did the WFH for a year, and while the freedom is enjoyable it is very easy
to slip into working very late going into 'hermit mode'. You have to be very
diligent in training yourself to be productive during normal hours so you can
be social in the evening.

My new situation is categorized as flexible office hours. I go into the office
2-3 days a week, enjoy good rapport with the people I work with, then WFH on
Mondays and Fridays (typically). I find this to be a good balance - I have
enough structure Tuesday to Thursday that I can continue this trend Monday and
Friday.

------
dajohnson89
Is the grammatical error in the title intentional?

~~~
TulliusCicero
I blame English. That language is always up to no well: [https://www.smbc-
comics.com/comic/noun](https://www.smbc-comics.com/comic/noun)

------
alwaysreading
Love the idea of starting with “what will the user be doing?” and prioritizing
based on that question.

------
GuiA
_...You can also make Tracker show a window for a particular folder in order
to show the user where a particular file has been stored and give him access
to it directly...._

 _...By removing unneeded items from the file navigation window, you are
reducing the number of choices the user must pick from and also preventing him
from opening the wrong kinds of files..._

 _...Good feedback just means making sure that the user knows what your
program is doing at any given time, especially if the program is busy doing
something which makes him wait..._

 _...An even better solution would be to select a good default choice for the
user and give him the option to change it..._

 _... In short, a user will learn only what he must in order to do his job..._

Ctrl-F "her", "she": 0 matches

Another tip to design good software: don't assume all your users are male :)

This is an okay stab at a HIG, although it is severely lacking in examples and
screenshots, for a document that deals with _graphical_ user interfaces.

Good past attempts that are worth the read if you're into this kind of stuff
include the original Macintosh HIG, as well as NextStep User Interface
Guidelines. I also quite liked the _Hypercard Stack Design Guidelines_. Gnome
once had an okay-ish HIG (which I contributed to), not sure how well up to
date it's been kept through the years. KDE, despite being better on the eye
candy front compared to Gnome, was always lacking behind in terms of actual
concrete guidelines for developers.

~~~
waddlesplash
This document was mostly written almost a decade ago, and by someone who I
think went to a prestigious institution. So the "rules of style" back then
aren't what they are today.

You're right, we should update it, though.

~~~
anonytrary
> You're right, we should update it, though.

No, you really shouldn't, it's not a real problem. The only people who keep
tallies of gender pronouns in documents are internet trolls; don't indulge the
trolls. Anyway, switching up pronouns every other time breaks continuity and
makes documents harder and painful to read.

~~~
GuiA
No need to keep a tally; in 2018, any document that exclusively uses masculine
pronouns for genderless subjects reads as outdated.

When writing on technical topics, the chief concern is to be clear, accurate,
and straightforward. Anything that might distract your reader is undesirable.
By referring to “the user” as “he”, you’re already distracting roughly 50% of
your potential readership (if you’re writing the documentation for a Do It
Yourself Vasectomy Kit, perhaps you get a pass).

Switching up pronouns every other time is a strategy, but it is indeed one
that can hurt the readability of a document. This article covers various
strategies nicely:

[https://www.herodios.com/pronouns.html](https://www.herodios.com/pronouns.html)

(Note that this document was written over 20 years ago, so the “rules of
style” when this document was written were roughly the same as they are now)

~~~
anonytrary
> By referring to “the user” as “he”, you’re already distracting roughly 50%
> of your potential readership (if you’re writing the documentation for a Do
> It Yourself Vasectomy Kit, perhaps you get a pass).

Do you have any research/data to back this up? I'm a male and I am not
distracted when people use "she" (or "he" for that matter). I have never heard
anyone in person complain about not being able to focus on an article because
they used "he" instead of "she".

> Anything that might distract your reader is undesirable.

Concision is of utmost importance in any language. Many of the examples in
your link sacrifice readability and concision for the purpose of avoiding
pronouns. What really distracts me is when people use "(s)he", "s/he", "he or
she" (oh no -- which one should be first?), or periodically switch between
"he" and "she" absolutely _everywhere_ \-- all for the purpose of filling a
contrived equality quota.

~~~
mixmastamyk
We need an "it" that can be applied to a person.

~~~
dragonwriter
English has had one for a long time, “they”.

Elitist prescriptivists who wanted English to be Latin because of bizarre
linguistic fashion tried to purge it, but never did from general use, and
prescriptivism, especially on points that have never aligned with common
usage,has fallen out of favor, so there is little reason not to use it now but
adherence to a particularly archaic elitism.

~~~
mixmastamyk
It’s useful to have a singular and plural form, required probably not.

