The Principle of Least Surprise

In computer engineering, more precisely pertaining more to the design of user interfaces, the "principle of least surprise" is a design principle where an interface is supposed to be similar to previously designed interfaces for the sake of continuity.

For instance, a good example of a violation of the principle of least surprise, would be the usage of a diskette icon to close the program instead of saving the current state of the program.

Documentation vs. Application Programmer Interface

One of the giant problems of our times is the lack of "documentation" for seemingly good software which in turn makes the software itself unusable in many cases. Even though automated tools are available for generating Application Programmer Interface (API) documentation, more than often, developers consider that the API itself is equivalent to documentation. This is applicable to the very many software packages that use Swagger and other tools to generate API documentation, especially where REST and other interoperability is involved. In reality, documentation is a superset of the API and involves much more than an API can provide such as:

  • coding examples,
  • case scenarios,
  • limitations,
  • etc

that are essential to any developer thinking to use the software as a component in their own workflow. Documentation is tough to write and needs some dedication to maintain given the changes between various releases of a software package such that it is no wonder the developers just prefer the tool output that generates API documentation instead of dedicating time to write proper documentation.

Either way, as it stands, it is important to remember that "documentation" is not synonymous with "API documentation" and that "documentation" consists in a superset that includes "API documentation" but along with much more.


fuss/computer_engineering.txt ยท Last modified: 2025/05/22 12:55 by 127.0.0.1

Wizardry and Steamworks

© 2025 Wizardry and Steamworks

Access website using Tor Access website using i2p Wizardry and Steamworks PGP Key


For the contact, copyright, license, warranty and privacy terms for the usage of this website please see the contact, license, privacy, copyright.