Designing Interfaces

Interfaces are the main tool for managing complexity and building software systems which are useful for others.

Good interfaces allow consumers to benefit from the externally-facing results without having to concern themselves with its internals and implementation details.

Interfaces manifest themselves various forms: User interfaces (UX/UI), REST APIs, and even methods and properties of a class.

What all of these forms have in common is that the consumers -- the end-user, customer, a developer integrating with a system, or even yourself in the future with a fainter memory of the details -- will benefit from a well-designed interface.

Simple as possible

When in doubt, the simpler solution is often the correct one -- or at least the best at the time, until more is learned. The reason being that complexity introduces a barrier, causes confusion, and requires more time to correctly implement and for consumers to understand.

I do not deny that there are occasions when solving a complex problem that a complex interface will be required. But the point here is: don't start there. Erring to the side of simplicity is very rarely a mistake.

Start simple and wait for a strong reason -- and a strong value proposition -- to go complex.

Obvious and self-evident

An interface is the way that the software presents itself for potential consumers so, as a rule of thumb, “if it needs explaining, it has already failed”.

Strictly speaking, this is an exaggeration, but I think the underlying message is valuable: design for it to be as obvious as possible; follow what the user most likely expects, drawing from their past experiences with similar software; and follow industry-wide wording and conventions, unless there's a very strong reason not to.

One can argue that the only reason to deviate from the “obvious” and the “boring” is when your value proposition is directly tied to doing it differently.

There's no excuse for bad documentation

If the purpose of your piece of software is to be useful for other people, failing to properly document it goes contrary to that goal in a very obvious manner.

Documentation is not simply an auto-generated dump derived from the code. That can only ever explain WHAT things are.

Good documentation explains HOW someone is supposed to use it for their own goals, and possibly documents WHY things are designed a certain way.

Forward evolving, backwards compatible

Software requirements are a moving target, as the business evolves to accommodate changing customer demands. With this in mind, it is a integral component of designing an interface accommodating for the fact it will change in the future.

As much as possible, this must be done with minimal disruption to existing consumers. There's little perceived value in re-learning something that already works or re-implementing some integration while risking new bugs and unforeseen consequences.

For the interface owner, it's often easy to ignore the cost of a breaking change, as they will most likely not be the one to bear the burden. But, again, the purpose of an interface is to be useful for others and that is achieved with stability over time and supporting usage flows that user's came to rely upon.