My team is discussing how we should indicate, in a logbook, whether a specific action ended with success or not. I started putting it like

timestamp | action name (fail)    | description
timestamp | action name (success) | description

One of the team members suggested replacing fail/success with OK/NOK:

timestamp | first action name (OK)    | description
timestamp | 2nd action name (NOK)     | description

I wouldn't mind such a detail, if he didn't say it would improve readability. I doubt it:

  1. OK and NOK correlate to 66 %, so arguably when quickly going through a lot of text, it is probable to confuse NOK for OK. To the contrary, fail has 0 correlation with success.
  2. fail has a varying letter height, which success doesn't, making them look very different.

Am I thinking in the right direction? Is there any resource where I can read about such details? I believe something like this should be very well known in the area of cockpit or nuclear power plant control room design.

  • 102
    Yeah I don't really know what NOK means – Majo0od Jun 7 '16 at 14:08
  • 11
    Also improving readability how? Honestly to me fail/success improves readability since I'm able to make a very clear distinction between the two. – Majo0od Jun 7 '16 at 14:11
  • 27
    NOK is not a very common, it apparently has 3 more common definitions that I'd argue are also uncommon. – DasBeasto Jun 7 '16 at 14:12
  • 86
    I would say this is NOK – Midas Jun 7 '16 at 14:34
  • 39
    If success is the normal, common state, why print "success" at all. Just print FAIL whenever a task failed? – user31143 Jun 7 '16 at 14:59

13 Answers 13

up vote 23 down vote accepted

It appears that the biggest problem is being able to find the status indicators within a large group of text.

Barring some significant technical limitation, I would say your solution should be to display the status of each action in its own column.

This makes your question of exact terminology much less important by

  • Reducing the importance of terminology for the sake of visibility
  • Providing a clear, easy to scan column that displays the statuses in a consistent location

But to actually answer your question, I'd go with the "fail/success" pair without considering the exact context in which you're displaying this information.

If the output is binary (success/fail, OK/NOK, whatever), why not only show a status on the failure state?

timestamp | action name           | description
timestamp | action name           | description
timestamp | action name (FAILED)  | description
timestamp | action name           | description

Edit:

Some comments to the original question have mentioned that the ability to quickly scan and find errors is desired. In that case, I would recommend adding an additional column, but still only displaying failed cases.

For example:

  | timestamp | action name           | description
  | timestamp | action name           | description
! | timestamp | action name (FAILED)  | description
  | timestamp | action name           | description
  • 15
    One minor consideration here is if it's possible (and it usually is, even if you don't think it is) that the task could silently fail, get stuck, never complete, or the status reporting itself could fail, etc. In an ideal world you might have a temporary status like (Working...) or In progress... that is removed on success or failure, so when skimming a list, the "stuck" tasks stand out as much as cases where the task failed but the failure reporting succeeded. – user568458 Jun 8 '16 at 8:25
  • 3
    @user568458 often you can't just change what you've previously logged. – OrangeDog Jun 8 '16 at 10:29
  • 5
    @OrangeDog yeah, that sort of limitation is why I say "in an ideal world". The important thing is avoiding a situation where if a task gets stuck, or if everything fails including the error logging, the output makes it look like a success. For old-school logging appending to a file, options could maybe include only writing the output on completion (so stuck tasks would be completely absent), or only writing the description on completion (so stuck tasks would be noticeably incomplete) – user568458 Jun 8 '16 at 10:41
  • 1
    If you don't mind unicode, you can also use the check mark character (U+2713): action name ✓ for successfull operations (if there is a third state, where an action is still not completed) – Falco Jun 9 '16 at 8:49
  • 1
    @Falco I like the idea of marking completed actions, but I would lean more towards only marking actions that fail or don't complete. Assuming that most actions won't fail, a column that's blank for the majority of lines makes it easier to find the problematic lines. – Harrison Paine Jun 10 '16 at 18:29

What you need to examine is the use-case for these terms within the context of the project logbook. I have to guess here but I'd say the logbook is a project management tool - an aid to charting progress or discovering problems/blockers

'NOK' is not a commonly understood term. This means that anyone joining your team for reasons of scale, sickness cover, etc, as well as anyone outside your team auditing the project would need to have this term explained to them. Whereas 'success' and 'fail' make perfect sense to anyone capable of reading English.

If you want to improve the visibility of one or other of the two states then I suggest you look for a non-linguistic solution such as placing a shape next to failed items in the list.

Two things to think about:

In computing, it's common to use failure instead of just fail, because it happens to be the same number of characters as 'success', so in mono-spaced fonts they end up being the same width. (Side note: "warning" is also the same number of characters) In addition to this, some systems (like Linux/Unix) color the words - failure is usually colored red, and success is usually colored green/blue. So in these systems it's not the [dis]similarity of the words, or the fact they have the same character width that helps identify warnings/errors, it's the color that helps identify failures.

Word coloring is one technique I've seen in the aerospace industry, used with actual avionics equipment in cock pits.

The fact that success, failure, and warning are the same length means that the log message will start at the same location on each line. Eg:

timestamp | action | FAILURE | message/description
timestamp | action | WARNING | message/description
timestamp | action | SUCCESS | message/description

Which can help many people with readability. It's easy to ignore the first 3 columns if they're all the same width. And once you've identified failures/warnings, the most important columns for a human is probably the message/description. Action may be important, but if you see the error message you'll usually have a clue about what to do regardless of what action was taking place. Consider this [slightly contrived] counter-example where each status is a different width:

timestamp | action | fail | message/description
timestamp | action | successful | message/description
timestamp | action | warning | message/description

Now think of seeing that with dozens or hundreds of lines - it gets hard figure out where you need to focus your attention. Of course the simple fix there is to pad the status field with spaces, but then you might lull yourself into discerning status based on word width in the status column (which seems to be your current dilemma).


At least in the aerospace industry, I've seen the use of "GO/NO-GO" for indicating status. NO-GO can also be represented as NOGO or NGO, which is similar to your NOK. I would argue that this is much more widely known, used, and easy to understand for newcomers. And it assuages the concerns many commenters and some answers have pointed out in the more uncommon "NOT OK"/"NOK".

So I would probably do a bit of everything, if possible - take Andrew Martin's answer and use a symbol, color the letters, and pad spaces so the actual messages that you (as a human) want to read are all lined up. Of course this all depends on what kind of UI/format we're talking about - terminal? text file? rich text file? HTML? etc

  • I was going to suggest coloring but even avoiding words altogether if possible. A simple red and green dot would probably be best if there is a brief explanation of what red and green means. – Rob Jun 7 '16 at 21:30
  • you can leave the padding out, if you reorder the columns. you can use timestamp | failure | action | message and you won't need any padding because the first three columns start on the same letter number/ – Armin Jun 8 '16 at 2:31
  • 6
    @Rob don't forget colorblindness. Red and green are good as additional cues, but they must not be the only way to distinguish between things. – user31143 Jun 8 '16 at 5:30
  • @dan1111 Then black and white or gray. Or is it grey? – Rob Jun 8 '16 at 13:12
  • 2
    I think relying on anecdote and personal experience for whether a term is more widely known is very dangerous if you are talking about newcomers to the system. "NGO" and "NG" are just as alien to me as "NOK"; as far as I'm concerned you might as well use "ZQX", because I would read all of them as "this column normally says OK, so I guess this means something went wrong". – IMSoP Jun 9 '16 at 11:43

You could use pass/fail. This would satisfy the condition of making the words look different, but has the advantage of being the same number of characters.

timestamp | action name (fail) | description
timestamp | action name (pass) | description

At a guess, I think your colleague is talking about readability because of verbosity. i.e. he doesn't want the success / fail to make the description harder to read

So why not have just (!) for failures, and nothing for success

timestamp | first action name       | description
timestamp | 2nd action name (!)     | description

This isn't usable for a first-time user as you'd have to explain that. However this is a log file so I wouldn't expect basic users to be looking at it but hopefully any developer should understand this and remember this as soon as they've been told it once.

At least this might get your colleague off NOK and will save you some bytes along the way.

Edit: I've now just spotted this is somewhat similar to @Andrew Martin's answer

I think the reason is psychological and has nothing to do with readability.

A NOK, not-OK, sounds way less harsh then a FAIL, FAILURE or ERROR. It's just a way to not have to use those "negative" words.

In my opinion you should not budge.

  • Though it was not the question, I appreciate your elaboration on the topic. NOK is a typical term in our environment, so it wasn't the essence of the problem. But I never took care to think why we are using this strange NOK. – texnic Jun 10 '16 at 20:57

I know this thread is old, but in case anyone finds this useful: I don't know where you are from, or what field you work in, but in my field (industrial automation), OK/NOK are a de facto standard in Europe. If your colleague used to work/works in automation, maybe it is just what he is used to. However, I would point out that these are mostly shown on color screens and usually accompanied with green/red color. In a plain text log, I would definitely choose another way, unless the customer specified otherwise. Most likely what Harrison Paine suggested - no text for OK result and whatever you want for Not OK result.

As a further consideration, "OK/NOK" is clearly binary and only allows two possibilities. "Success" and "fail" more clearly allows for further possibilities - "warning" has already been described above as a third state, or "could not run" if preconditions are wrong, or "comms error" if the test was started but you couldn't get data back, or... You get the idea.

When looking at a log file there are two very important things. First finding the problem (or information) quickly, and being able to search for that information.

timestamp STATUS Action Details of the log entry 
timestamp STATUS Action Details of the log entry
timestamp STATUS Action Details of the log entry

Should do that quite nicely. It's important that time-stamp and STATUS are left most. First because it's easier to line up, and second because it's what you care the most about. You start out with a "failure around 6pm". So you scroll to 6pm time stamp and start hunting for a failure.

Next issue is the ability to search log files. No one ever reads /var/log/syslog unless there having a really bad day. Instead they either tail it of grep it. With that in mind you want to have a FAIL and a OK look very different. I prefer -OK- and FAIL. Again this makes line up trivial, but more importantly my eyes can catch the difference between the two if they change rapidly. That is important for tail -f /some/log/file

It also works well with greping cat /some/log/file | grep FAIL will work very well. NOK and OK will not. They will both match "OK".

In short use -OK- and FAIL admins everywhere will appreciate that.

  • for the other statuses in some of the comments and answers you can use WORK and WARN – coteyr Jun 9 '16 at 16:06
  • The question was about a logbook, not a log-file. Therefore the width is not an issue. It could be hand-written :) – texnic Jun 10 '16 at 20:55

If you're just looking to replace the harshness of "FAIL", I'd suggest GO/NO GO.

In addition to give you a alternative to "success/fail", it gives your meetings a NASA-esque feel to them.

If your output device supports colour, you could colour-code the text in addition to putting a status message next to it. That way, it will be easy to see what was successful and what failed, no matter what actual text is used. You wouldn't have to store the colour information in the log file, but could add it dynamically when the log is displayed (this depends on whether or not your log file is displayed in a text viewer or in a bespoke log viewer).

Remember though that colourblind users may not be able to see red and green clearly, so make sure that there is some way to configure the colours used or offer an alternative black-and-white version (i.e. you still need a status message, not just colours).

NOK is definitely confusing. I'd personally go with Ryan's answer (FAILURE/WARNING/SUCCESS), but it's worth to mention another "standard": OK/KO. It's short, they have the same number of characters, it's understandable (KO is clearer than NOK I believe), but it lacks semantics compared to FAILURE/WARNING/SUCCESS.

Update: It seems OK/KO is specific to France, I didn't know that before

  • 19
    Let's try this out: OK OK OK OK OK OK OK OK OK KO OK OK OK OK OK OK OK OK OK OK OK OK KO OK OK OK << Quick! How many failures occurred? – Substantial Jun 8 '16 at 10:54
  • 1
    @Substantial: 2 – Bolu Jun 8 '16 at 12:26
  • 3
    Yeah, except the author prints new lines every time, not a sequence of OK KO, so no – Thiht Jun 9 '16 at 11:52
  • 3
    -1. If I just saw "KO" as a status, I would have no idea what that meant. However, if I saw "Success" as a status, I would have no questions at all. – maxathousand Jun 9 '16 at 15:23
  • 1
    OK/KO is very popular in France but is not understood outside. – jlliagre Jun 10 '16 at 20:31

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.