TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Fatal and unused - full text From:Sandy Harris <sandy -at- storm -dot- ca> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Mon, 10 Dec 2001 08:22:42 -0500
Jane Carnall wrote:
>
> There are five types of log file on the platform that we supply to outside
> developers. The fifth type is "Fatal".
>
> The note the SME provided for it said:
>
> FATAL - used for very serious problems that may cause the whole system to
> fall over (please don't write any code which needs this log).
>
> I rewrote:
>
> Fatal is used to log very serious problems that can cause the whole system
> to crash. We have not provided an example because we don't actually want you
> to ever need to use this log, or worse yet, cause us to need to use it.
>
> (All of the other log type descriptions are provided with an example.)
>
> I'm not sure the second sentence is necessary, but I liked it. It seems odd
> but it's certainly logical to tell outside developers that we don't want
> them find themselves using this type of log but that it does exist. Input?
I'm making some assumptions, based on what I think "fatal" means, that may
not apply in your system. What I'd write would be something like:
Fatal indicates a problem serious enough that the program cannot continue.
If it did continue, it would almost certainly crash, so it shutting down
instead. Think of the message as a suicide note from the program.
Typically, these messages arise when required resources are unavailable.
For example, an attempt to open or write a file, to allocate memory or
to start a child process can fail. If retrying makes sense in your
application -- for example if you can wait fice seconds and try starting
the process again -- then the failure is a loggable event but not Fatal.
If retries do not make sense for your application or if retries fail and
you give up, then it is a Fatal error.
For example, a program that cannot open its configuration file might
consider that a fatal error. On the other hand, it might continue
using built-in defailt settings.
Your code should use this log only for unexpected failures based on
external resource constraints. If your program cannot run because
the disk is full or someone removed a critical file, that is a
legitimate fatal error.
Please do not ever use this log for a situation where your program
cannot run because some resource it manages is fouled up. For example,
if the count of elements in an internal queue becomes negative.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.