RE: Notes, tips, and warnings... oh my!

[KMcLauchlan -at- chrysalis-its -dot- com]

This discussion of Notes and tips is interesting to me.
I'm facing related issues and dealing with them 
in less than exemplary fashion, just now, as I 
try to navigate the thicket.

Embed the notes? Makes for multi-paragraph single 
steps, sometimes. Not good.

Insert them between steps? OK, but some people 
have said that's distracting or can be ignored 
by glazed eyeballs that look only for active verbs.

Make sidebars? Same objection, plus some of 
the explanations are too big for my little 
sidebar boxes.

SCENARIO
We make and sell some little devices that can 
be central to the continuation of a client's 
business.

The product has a number of options that can 
remain off, or be switched on singly or in combination, 
permitting a spectrum of possible levels of system 
security. 

That is, you can go with the vanilla setup and have 
excellent security for your data, encryption/signing 
keys, digital certificates, etc., or you can elect 
one or more of the options, until you achieve ultra-
paranoid security. The problem is, those features 
impose greater and greater complexity on your operations, 
as you achieve greater and greater security.
It's a trade-off.

The thing is, once you 'go live', you can't just decide 
to switch off some inconvenient features if you determine 
that the greater security is just not worth the practical 
difficulties.
That's not merely our call, as the manufacturer. 
Industry and government certifying bodies have said 
that we may not allow the possibility to simply switch 
off a previously activated onerous security requirement. 
To keep our certifications, we can't allow the devices 
to "backslide".

On the other hand, you can't just opt for the minimum 
and then elect to impose "harsher measures" later on, 
because your clients seem to want them. If your data or keys 
began life with only "level 1" security, and you later 
transfer them to "level 3" containers, a security analyst 
will rightly point out that those data or keys still enjoy 
only a "Level 1" confidence. If, at some time in their little 
lives they existed at a lower security state, then they 
are effectively "tainted" by that history and can never 
claim the same confidence level as objects that have 
never been outside a higher-security envelope.

So, the point is that you need to consider a lot of this 
stuff before you make configuration/initializatin choices.
You need to plan ahead when you are initializing 
a system. You want to be able to brag of truly profound 
security for the benefit of your customers. But, on the 
other hand, you don't want to impose requirements on 
your staff that cost too much in time, effort, cash, 
redundancy, whatever.  (Do we REALLY, really need to get 
John from Singapore, Teri from Ankara, Sydney from Sydney, 
and Pat from Dublin to fly in and simultaneously present 
their physical access tokens and type in their PINs, 
every time we wish to access the master root key? Maybe 
yes, maybe no, but decide *before* you lock in the 
requirement and generate working keys/certificates.)

That's just the security stuff. There are also choices 
that have to do with the platform and the application 
on which you are installing our stuff. To keep the docs 
sorta generic, I don't mention a specific company's 
application by name. Instead, I might say "If your PKI 
application works in THIS fashion, then select this 
configuration option. If your application works in THAT 
fashion, then select this other option..." Naturally, 
"this fashion" and "that fashion" take a LOT more 
words to describe on the page(s)

So, how do you want all the facts and notes and 
cautions presented to you?

Currently, I'm leaning toward "Please be sure that you 
have read and understood Appendix C [D][E][F][...] before 
performing the next step."

I dunno. Pile it all in with the steps and tangle the 
customer in a morass? Organize it all nicely, elsewhere, 
and force the customer to jump back and forth? 
Either one is bad, for different reasons. Oh, and 
it's paper docs, mostly.

I do provide a little pre-amble that says the majority 
of customers can get away with the default level 
and the fewest authentication options. And I offer an 
admonition to know your own security requirements and 
plan your security and operational procedures before 
you start configuring our product, but... who really 
reads that stuff?

Waddya say?

Oh my!

/kevin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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.