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: 4, Interesting) by Rich on Friday August 18 2017, @10:21AM (6 children)
Page 311 f.: "A good alert box message says what went wrong, why it went wrong, and what the user can do about it. Try to express everything in the user’s vocabulary.". From the First Printing, November 1992.
In the Microsoft world, a lot of software fails as far as the second sentence is concerned. I (think I) have a deep understanding of how computers work, and how to make them work, but I very rarely get involved with Windows. It baffles me each time I see one of those error messages, where both noun and verb of what just failed seem to be straight out of an advanced level MCSE exam. And if you believe that close boxes have to be on the right, and OK buttons on the left, your mind has been poisoned by the toxic Redmond influence and will probably also write error messages in this MCSE lingo. A lot of Linux developers come from the MS side, so they don't know any better. Yet, a large number of people insist that Gnome 2 had it (and MATE still has it) right - hint: Their main, user facing software was written by Mac and Mac Finder (Classic) veterans.
Aside from the wording, there's one thing, particularly with newer software, that wants to belong into the "Just Works" class: The developers think they can entirely ignore error messages, because, well, it just works. Except it doesn't. And it certainly doesn't, if any online connection is required. It is immensely frustrating to see a work indicator (spinning wheel or so, and also opposed to a progress indicator, which might even give subtle clues on where something just got stuck) just continue indicating work, without anything happening.
It is my personal belief that in this case, no action should take more than two seconds, but if it absolutely has to (eg CPU time), for some reason, it needs accurate progress indicating, And if it fails, there should be usable diagnostics hidden under an "Advanced" diagnostics tab in the error messages. E.g. "The network seems to be up, and I could resolve the name, but the cooking recipe server (recipes.cooking.com, at 123.45.6.78) does not respond."
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. Unfortunately even the originating company doesn't adhere to it anymore.
(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.
(Score: 2) by c0lo on Friday August 18 2017, @11:15AM
"Glue too old, adherence aborted"
https://www.youtube.com/watch?v=aoFiw2jMy-0 https://soylentnews.org/~MichaelDavidCrawford
(Score: 0) by Anonymous Coward on Friday August 18 2017, @12:34PM
Microsoft tends to lump several user-visible error messages into one, and shows a couple of options that could maybe be the problem.
The classic from IE: "The server was not found, or a DNS error occurred". If the server wasn't found, or a DNS error prevented you from getting the IP address of the server, how come I can see the request on the server? Heck, I've even had that error message while having the server code stop at a break point.
It seems to me that that error message is the one shown for any error between GET / POST and having a complete response.
(Score: 0) by Anonymous Coward on Friday August 18 2017, @12:56PM
Uh, Microsoft normally fails all 3 criteria completely.
It just says "Error: 0x...."
You don't even get to know WHAT failed, you can only guess it from context. Certainly not why, and what to do about it? Microsoft themselves obviously don't know at least half the time, at least when one of their updates fails to install. AGAIN.
(Score: 0) by Anonymous Coward on Friday August 18 2017, @02:40PM
Developers of newer moBILE themed soffware also desire to cut localization costs by using abstract text-less icons and as little other text as possible. It's all part of the (cost cutting) plan.