SoylentNews is people
SoylentNews
Submitted via IRC for TheMightyBuzzard
Try this simple technique to write messages that help users understand the reason for errors.
The first time a user encounters an application's documentation, it's not always with the user manual or online help. Often, that first encounter with documentation is an error message.
Technical writers should be involved in writing error messages. It's an important, although often overlooked, part of the job. After all, error messages are documentation, albeit documentation that's embedded in the code.
[...] An error message should be meaningful. By that, I mean full of meaning not only for a developer, but also for the user of the software. To prevent any panic or confusion, the message should be clear.
A meaningful error message should:
- be short (you can write in sentence fragments);
- contain a description, in plain language, of what went wrong; and
- use wording or a tone that doesn't (whether explicitly or not) blame the user.
Source: https://opensource.com/article/17/8/write-effective-error-messages
(Score: 0) by Anonymous Coward on Friday August 18 2017, @10:36AM (1 child)
> ps: Oh, you didn't know, what "NIM:HIG" means?! I took that for, like, totally, granted. It's "New Inside Macintosh: Macintosh Human Interface Guidelines", ISBN 0-201-62216-5.
Nitpick: isn't that "NIM:MHIG"?
(Score: 2) by Rich on Friday August 18 2017, @11:09AM
It should be, heh?! But from the times of lore, there are precursor documents, which lacked the "Macintosh". I have one older book in hardcopy, but I must've misplaced it. There also used to be a detailed description of how to use the text-only file card metaphor from AppleWorks (classic) on the II. IIRC, that was "Apple Human Interface Guidelines" (and the HIG part stuck). Which is long forgotten now, especially since IBM came up with the "let's fake a mouse workflow on text screens" SAA behaviour and MS borrowed from that. It introduced "OK" on left, because (and here you get the reason) that was meant to be the first button to be reached when tab-ing through a form (whereas on a pure mouse workflow, the natural completion of working down a page is in the bottom right corner (or left, with RTL scripts).
Eventually Apple re-wrote the book for the New Inside Mac series (which still is the best programming documentation ever... seen their present docs on MIDI programming???), so the "Macintosh" also went into the title.