-
Notifications
You must be signed in to change notification settings - Fork 0
/
custom-software-errors.html
446 lines (388 loc) · 17.1 KB
/
custom-software-errors.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2024-09-08 Sun 19:44 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Higher quality errors for custom software.</title>
<meta name="generator" content="Org Mode" />
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<link rel="stylesheet" href="reset.css">
<link rel="stylesheet" href="index.css">
<meta name="author" content="Wade Mealing" />
<meta name="description" content="Seriously useful error messages" />
<meta http-equiv="Content-Security-Policy" content="default-src 'self' 'unsafe-inline'; img-src https://*; child-src 'none';" />
</head>
<body>
<div id="content" class="content">
<h1 class="title">Higher quality errors for custom software.</h1>
<div id="outline-container-org92724de" class="outline-2">
<h2 id="org92724de">Summary:</h2>
<div class="outline-text-2" id="text-org92724de">
<p>
In-house business software is a very different beast; it is usually target-built to solve
a very specific problem. Company bean counters encourage buying off-the-shelf software when it is
advertised to solve a problem. Sometimes the benefits of customized, specific software
can provide too much value, and the company can't turn away from those sweet productivity gains, so
custom software will be created.
</p>
<p>
Because the software is created with customized intent, the error messages presented to users can have
additional benefits that off-the-shelf software doesn't offer. Business process backed error messages.
</p>
<p>
In the company I work at, these improved error helpers are called "Wilbert-Hofmann" error messages.
It would be great to see these error types in wider use.
</p>
</div>
</div>
<div id="outline-container-org4fa2b56" class="outline-2">
<h2 id="org4fa2b56">Introduction</h2>
<div class="outline-text-2" id="text-org4fa2b56">
<p>
Effective resolution of errors plays a pivotal role in shaping the user experience within
software applications. The content of the messages, along with information, should not only
alert users of the problem but also equip them with the necessary resources to
troubleshoot effectively, even in challenging scenarios.
</p>
<p>
Contrary to the notion that error messages are an "anti-pattern" indicative of weaknesses
in code or design, they serve as vital conduits of information for end users. Familiarity with error
messages and their corresponding well-known user-interaction patterns show how deeply engrained error
handling is.
</p>
</div>
<div id="outline-container-org777a968" class="outline-3">
<h3 id="org777a968">The basics.</h3>
<div class="outline-text-3" id="text-org777a968">
<p>
Rather than re-iterate what has already been said, Google has a very good course, in the <a href="https://developers.google.com/tech-writing/error-messages/error-handling">technical writing</a>
category, which focuses on writing better error messages. It also contains excellent advice for programmers
when generating errors for their users.
</p>
<p>
To paraphrase, the best errors are:
</p>
<ul class="org-ul">
<li>Deliver the best user experience.</li>
<li>Are actionable.</li>
<li>Are universally accessible.</li>
<li>Enable users to help themselves.</li>
<li>Reduce the support workload.</li>
<li>Enable faster resolution of issues.</li>
</ul>
<p>
The original course is aimed at writing software for general use, but if the software is intended
for use in a corporate setting, additional features can be added to error messages.
</p>
<p>
I would like to believe that a certain subset of users are capable of solving many problems they
run into, and are also able to help others who can run into the same problem.
</p>
</div>
</div>
</div>
<div id="outline-container-org37d649a" class="outline-2">
<h2 id="org37d649a">Improved example.</h2>
<div class="outline-text-2" id="text-org37d649a">
<p>
So, let's provide a before and after. This particular example was chosen as a bland and boring
example so we wouldn't focus on the error itself.
</p>
<p>
Kept in ascii art to remove distractions and debate on how poor my CSS theming skills are.
</p>
</div>
<div id="outline-container-org153c6ea" class="outline-3">
<h3 id="org153c6ea">Before:</h3>
<div class="outline-text-3" id="text-org153c6ea">
<pre class="example" id="orgae3bbac">
|--------------------------------------------------------------|
| ⚠️ Error: |
| |
| Loan applications can not continue without approval. |
| |
| Approvals take between 2-3 business days after lodgement |
| |
| Please contact the approvals team if this needs expedition |
| |
| [ CANCEL ] [ OK ] |
| |
|--------------------------------------------------------------|
</pre>
</div>
</div>
<div id="outline-container-org61018bf" class="outline-3">
<h3 id="org61018bf">After:</h3>
<div class="outline-text-3" id="text-org61018bf">
<pre class="example" id="org8bfa692">
+------------------------------------------------------------------------+
| ⚠️ Error #90210C |
| |
| Loan applications can not continue without approval. |
| |
| Loan approvals take between 2-3 business days after lodgement |
| |
| Please contact the approvals team if this needs expedition |
| |
| [ CANCEL ] [ OK ] |
| |
+------------------------------------------------------------------------+
| CrowdSourced Docs | Message the Approvals Team | Approvals Queue | 📋 |
+------------------------------------------------------------------------+
</pre>
<p>
Each error condition should have at least 4 basic "error additions" not
seen in most traditional software.
</p>
<p>
The naming conventions need not match and should match the terminology and
tooling used in business; you should adjust accordingly.
</p>
<p>
– CrowdSourced Docs.
</p>
<p>
This will not be the first thing that an end user reads. We 'all know' that
nobody wants to read documentation; however that doesn't mean that it won't
be used.
</p>
<p>
Making documentation immediately linked to this exact error means that new
users can get additional information on documentation and update documentation
when they find an answer.
</p>
<p>
In most cases, this could be a company wiki, but it may also be something built
into the program itself if offered.
</p>
<p>
For example:
</p>
<div class="org-src-container">
<pre class="src src-html"><<span style="color: #e78c45;">a</span> <span style="color: #e7c547;">href</span>=<span style="color: #70c0b1;">"https://<organization>.com/documentation/<error-code>/"</span>>
Crowdsourced Docs.
</<span style="color: #e78c45;">a</span>>
</pre>
</div>
<p>
– Message the Approvals team (communicate with help).
</p>
<p>
This should be a direct link to the company's internal messaging platform; it may be Teams,
Slack, Discord, or email. It really doesn't matter as long as it gets to the right people
who can help deal with this particular error.
</p>
<p>
Programmers may believe this is useless or could confuse end users;
however, having the team directly responsible for the resolution available can reduce the back
and forth of contacting the wrong team to solve the wrong problem.
</p>
<p>
For example, the hyperlink:
</p>
<div class="org-src-container">
<pre class="src src-html"><<span style="color: #e78c45;">a</span> <span style="color: #e7c547;">href</span>=<span style="color: #70c0b1;">"https://<organization>.slack.com/messages/<channel>/"</span>>
Approvals Team Slack
</<span style="color: #e78c45;">a</span>>
</pre>
</div>
<p>
If the approvals team is more focused on emails, this instead could be a link to a template "mailto" url.
</p>
<div class="org-src-container">
<pre class="src src-html"><<span style="color: #e78c45;">a</span> <span style="color: #e7c547;">href</span>=<span style="color: #70c0b1;">"mailto:[email protected]?subject=This loan needs exposition&body=Please expedite loan id: 12345 because [insert reason here] "</span>>Email approvals</<span style="color: #e78c45;">a</span>>
</pre>
</div>
<p>
When clicked, the browser will fire the mailto protocol handler (mail program) with part of the template already filled out.
</p>
<p>
It doesn't have to be the approvals team, but if there is a support team that deals with the specific area, contact information should be here.
</p>
<p>
– Approvals Queue ( Advanced Information )
</p>
<p>
This is the "why" of the error condition. This is the part that we as programmers try to
hide from the user, however, I believe that for anything but the most basic of users, hiding
the logic behind why errors occur is a net loss.
</p>
<p>
For example, if there are several conditions that are not met in the approval process, but
you are also waiting for someone to approve the loan, this logic could be outlined.
</p>
<p>
Knowing the position in the queue, may mean they can re-prioritize work or understand if there
is no progress being made at all (Approvals people are on holiday). Exactly what this is will
depend on the error.
</p>
<p>
– The 📋 "Copy error to Clipboard" button (share this with someone helping)
</p>
<p>
Having the exact error message available with single click can reduce the
time to resolution. Without a simple way to copy and share errors, users will take poor
screenshots, incorrectly type out the message, or take photos of it with their phone camera
(including company confidential data).
</p>
<p>
Additional data to aid in resolution can be included in this clipboard to help someone
attempting to diagnose the problem, such as the <i>loan ID</i>, the <i>user ID</i> or <i>permissions</i>. If a
user's question could be solved with additional data, this is where the data should be included.
</p>
<p>
Exactly how to do this will depend on the platform being used, and in the worst-case scenario,
you can present the text to be copied to a clipboard if the underlying toolchain does not
support this functionality.
</p>
</div>
</div>
</div>
<div id="outline-container-orgee68a35" class="outline-2">
<h2 id="orgee68a35">Introducing change</h2>
<div class="outline-text-2" id="text-orgee68a35">
<p>
Rolling changes like this into an existing code base will likely be complicated; one possible
solution is incremental improvements.
</p>
<p>
Areas to start with can be identified either through application telemetry (i.e., how often
users view error messages) or by talking to support staff and dealing with the most frequent
offenders.
</p>
</div>
<div id="outline-container-org2796c5b" class="outline-3">
<h3 id="org2796c5b">Incremental Improvements</h3>
<div class="outline-text-3" id="text-org2796c5b">
<p>
Incremental improvement of error messages involves advancing beyond basic error handling. Not
all error conditions will benefit from the additional information. However, if there is an "error
display widget" used consistently in software, extending this widget to show this additional
data would be a great place to start.
</p>
</div>
</div>
<div id="outline-container-org8fc18e4" class="outline-3">
<h3 id="org8fc18e4">Error Categories.</h3>
<div class="outline-text-3" id="text-org8fc18e4">
<p>
Introducing a common "error category" simplifies the initial rollout of the new error fields. By
grouping related issues, error categories provide a simplified reference point, facilitating
collaboration and solution-sharing through wiki pages or discussion forums.
</p>
<p>
While there are effective categories for common errors, error categories alone are insufficient for
addressing complex or unique issues. Complex errors should be supplemented with robust reporting
and proactive problem-solving approaches addressing the specific issue.
</p>
</div>
</div>
<div id="outline-container-orgf0f42f3" class="outline-3">
<h3 id="orgf0f42f3">Unique Error Identifier</h3>
<div class="outline-text-3" id="text-orgf0f42f3">
<p>
By assigning distinct identifiers to each error condition, developers establish
a standardized method for identifying, tracking, and managing errors throughout the
software lifecycle. This systematic approach enhances the clarity and precision of error
reporting, enabling developers and users alike to pinpoint specific issues swiftly and
accurately.
</p>
<p>
Unique identifiers allow customers to quickly identify issues for support teams. When confronted
with an error, users can quickly reference the unique identifier to access relevant documentation,
seek assistance, or contribute to discussions regarding the resolution.
</p>
<p>
If the condition that creates the error is changed, new unique identifiers should be
used so that existing documentation doesn't contain out of date information. Do not
allow for unique identifiers to be duplicated across products unless they both
use the same source code with no variance.
</p>
</div>
</div>
<div id="outline-container-orgaf10be8" class="outline-3">
<h3 id="orgaf10be8">Online References (hyperlinks)</h3>
<div class="outline-text-3" id="text-orgaf10be8">
<p>
This is more than just linking to a wiki page; error pages could link to specific URI's of company
resources such as Slack, shared drives, or source repositories. If your userbase is sufficiently
technical it can also be a link to the source code for more capable users to self-diagnose the root cause.
</p>
</div>
</div>
<div id="outline-container-orgd30a0d4" class="outline-3">
<h3 id="orgd30a0d4">Extending this idea.</h3>
<div class="outline-text-3" id="text-orgd30a0d4">
<p>
I consider these 4 basics to be the first generation of improvements. You will find new
and useful improvements; do not be afraid to use them.
</p>
<p>
These "Wilbert-Hofmann" error messages are used heavily in the group of the company where I <a href="https://gitlab.com/cki-project/kernel-workflow/">work</a>.
</p>
</div>
</div>
<div id="outline-container-orgd1b3217" class="outline-3">
<h3 id="orgd1b3217">Generating documentation from error conditions for support staff.</h3>
<div class="outline-text-3" id="text-orgd1b3217">
<p>
Software should generate a list of error codes and their reasons for any of the support
staff who may be dealing with the area of code.
</p>
<p>
They could also use this to point to the area of code for additional inspection.
</p>
<p>
Should be notified of new error codes and if existing codes are removed or deprecated.
</p>
</div>
</div>
<div id="outline-container-orge948c46" class="outline-3">
<h3 id="orge948c46">Error analysis.</h3>
<div class="outline-text-3" id="text-orge948c46">
<p>
Analysis of the error messages
</p>
<ul class="org-ul">
<li>Count the number of times error links are visited.</li>
<li>Statistics on resolution or continued workflow.</li>
<li>Highlight staff training opportunties.</li>
<li>Determine areas where the user interface could be improved.</li>
</ul>
</div>
</div>
</div>
<div id="outline-container-org28831bc" class="outline-2">
<h2 id="org28831bc">Conclusion</h2>
<div class="outline-text-2" id="text-org28831bc">
<p>
The suggestions presented in this document serve as fundamental examples of extending common error
conditions to enhance the user experience and streamline error management. However, it's essential for
readers to recognize that these suggestions represent just the beginning.
</p>
<p>
When implementing these strategies, consider incorporating any additional resources and tools
that are relevant to the specific context of their errors. By continually expanding and refining
their error-handling capabilities, developers can ensure robust and effective error management within
their software systems.
</p>
</div>
</div>
<div id="outline-container-orgc994797" class="outline-2">
<h2 id="orgc994797">Resources:</h2>
<div class="outline-text-2" id="text-orgc994797">
<p>
<a href="https://www.smashingmagazine.com/2022/08/error-messages-ux-design/">https://www.smashingmagazine.com/2022/08/error-messages-ux-design/</a>
<a href="https://www.linkedin.com/pulse/how-write-good-error-messages-saadia-minhas">https://www.linkedin.com/pulse/how-write-good-error-messages-saadia-minhas</a>
<a href="https://uxwritinghub.com/error-message-examples/">https://uxwritinghub.com/error-message-examples/</a>
<a href="https://gitlab.com/cki-project/kernel-workflow/">https://gitlab.com/cki-project/kernel-workflow/</a>
</p>
</div>
</div>
</div>
</body>
</html>