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: What is not mandated is forbidden From:"McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com> To:Tony Chung <tonyc -at- tonychung -dot- ca> Date:Thu, 19 Jun 2014 15:09:01 -0400
Many of you probably work for companies that include open-source software in their products.
Some of y'all might recall a high-profile vulnerability (Heartbleed) in openssl 1.0.1e - through - g just as an example.
Other open-source software has its own issues (just as does proprietary software, except they don't tell you....) from time to time.
As these are observed, recognized, and reported, in the wild, they are prioritized and then fixed by the various open-source project people.
For companies using those components in their own products, sometimes it's enough to wait and just implement the updated release of the open-source component that has this-or-that fix. For others, they might need to implement a quick workaround/fix in their own product, because their customers aren't content to wait until open-source-project-X gets around to releasing the canonical fix.
Sometimes, your product might use an open-source component, but in a way that does not suffer any functional or security impact from a gap in the used component. Maybe you just don't use the vulnerable feature, so in your product's case it's a "don't care".
Your customers and potential customers, in the absence of any written statement of policy on such matters, will call and e-mail for reassurance, and X-many of your personnel will be tied up fielding those calls and e-mails and dispensing a boiler-plate response.
****
In a completely different example, many of you probably work for companies that offer products in spaces that have policing or overseeing organizations and standards, and your products must be validated against this-or-that standard. . . either to be allowed on the market, or to be viable in this-or-that niche.
A problem that's often encountered is that you get your product tested against version x.y.z of standard ABC, and the next version of ABC is in the revision committee process, which will take years... BUT, life goes on, and the testing labs that validate your stuff (and your competitors' stuff) against the existing standard are seeing conditions and usage undergo changes in the marketplace, and so they update their procedures and tests and checklists. They are still validating against a standard that's six years old, but their protocols have been updated a few times, and a product that passed 5 years ago would not pass today.
Now the above is not a problem if you don't change your product. But if you make any substantial change, you must re-submit in order to continue claiming that your product is validated, and this iteration of your product will now run up against the more recent testing protocols at the test/validation labs.
Instead of fielding calls whenever a competitor gets a "new" competing product validated against "the latest" ABC standard (or an old one re-evaluated), you could make a statement in your docs that describes the thresholds and milestones in your product certification/validation cycle.
Or not.
-----Original Message-----
From: techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+kevin -dot- mclauchlan=safenet-inc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Tony Chung
Sent: June-19-14 1:33 PM
To: McLauchlan, Kevin
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: What is not mandated is forbidden
My take is that now that a call is in progress, it belongs in the docs. If a call wasn't in progress, and the customers wouldn't know to ask because it's not in the docs, then It doesn't belong in the docs.
However, if omitting something from the docs could cause a critical failure, or babies would die, or something, then it should be in the docs.
Much of this falls under the category of "nice to know".
-T
On Thu, Jun 19, 2014 at 10:14 AM, McLauchlan, Kevin < Kevin -dot- McLauchlan -at- safenet-inc -dot- com> wrote:
> Does everyone subscribe to the notion that customer docs should
> contain only what is necessary?
>
> Is there a place for material that is good to know, or that might
> reduce customer inquiries, but is not necessarily critical to performing a task?
>
>
> The most recent example that prompted this thought was a statement in
> an e-mail thread (internal) where a PLM stated clearly and succinctly
> how 'discovered vulnerabilities' are handled for our products. I know
> that the question comes up, in different forms, with some regularity,
> so I asked if it would be good to include the two-sentence statement
> in the main customer docs. The answer was that it wasn't really
> necessary in the docs, as it was "marketing-speak to show how secure
> our stuff is". In a sense, that's true, but it was also a quick,
> clear description of the procedure we go through, and what the three possible outcomes are.
>
> I didn't push, because it wasn't terrifically important, and not every
> battle is worth fighting. But, as it stands, that statement exists
> only as guidance for techs and sales engineers to respond to customers who ask.
> So, by that point, there's already a call in progress. If they had
> seen the info in the docs, the call might never have been made.
>
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Doc-To-Help 2014 v1 now available. SharePoint 2013 support, NetHelp enhancements, and more. Read all about it.
