Metrics and process (was: How do hiring companies view TW resumes?

Subject: Metrics and process (was: How do hiring companies view TW resumes?
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 24 Mar 2010 13:53:14 -0400

Chris Despopoulos considered:

> Also useful would be the number
> of tech support calls -- more or less since the last doc
> version? Tech support is a quantifiable cost.

More or less.

I dare not name them, but a company that is involved in
identity security all over the planet recently complained
about the lack of some info in our product documents.

Basically, they wanted us to have included material in
a Java toolkit that was so basic that every java
developer does it automatically without thinking. You
can't get to _be_ a java developer without:

a) knowing that you have to do those actions
b) knowing how,
c) doing them before you even open somebody's toolkit
and start tinkering.

Our own java developers were scratching their heads.

It was a lot like when somebody butts into a conversation
and uses some buzzwords or technical terms in a way
that absolutely all participants - except the buttinsky -
immediately recognizes as wrong and completely uninformed.

We suspect the involvement of some sort of auditors who
know process but not the topic. Naturally, we jumped to
supply a "Technote" on official-looking company formatted

> Of course, if
> Tech Support generates revenue, then good documentation is
> quantitatively bad.

Indeed. When possible, work for a company that sells
support contracts, not one that charges per incident.

> I don't think we want to argue that case,
> though. You can measure support load via customer surveys,
> and also from the company's side as a count of Tech Support
> time over customer base. It probably makse sense to measure
> both if you can. And heck, Tech Support is a documentation
> customer. Include them in your survey. Get the Tech Support
> manager to indicate time saved because of the new docs, and
> turn that into a dollar figure.

I think that I'd have to inquire about time "un-lost". :-)

The data would show trends over time, but in many cases,
the trends would be visible only after considerable time.
We, in engineering (and customer pubs... all one of me in
this division) would we releasing the second or third
small - or large - subsequent release of the product since
we touched the one that is actually in the field in any
appreciable numbers. We have tight schedules to get
new revs released, but those are milestones to satisfy
particular customers or to have particular bragging
rights. There's always a follow-on delay while the new
rev becomes known (both inside the company and among
[potential] customers and orders start to flow.
There's also the delay inherent in company-to-company
purchases of /b/i/g/ non-trivial-ticket items. It's not
like a consumer product where you buy the one on the
shelf or you order from NewEgg and get it two days later,
paid with your credit card. It's a drawn-out purchase-req,
capital justification, approval process before the PO is
even ready for the customer to send to us.

Then, they might get the product and it sits in their
receiving until their own project reaches a necessary
point, and _then_ they unpack and start figuring out
how to work it - or program for it - or both. Customer Support
gets the first call for that release a year after I've
moved onto something newer.

This is especially a factor when agency approvals/validations
are needed by the major customers for a product. We might
have time for two additional bug-fix releases and a feature
bump, between the version they currently have, that's (say)
FIPS 140-2 level 3 validated and the validation of the
next candidate - can be a year or more. Same with Common
Criteria EAL which can take two or more years in process.

That's troubling when you consider that most electronic
products have a five-year life. You design with established
validated components - which means that those components
have already existed in the exact form that you specify
to be built into your product... which means those
components are already partway through their own product
life cycles before you ever start using them. A few years
later, your suppliers are discontinuing the specific
components (memory, circuit boards, power supplies, ICs)
that you specified for your product, so it won't be long
before you can't get the pieces to manufacture it any
more. You have to start ordering final big batches to
allow you to make final manufacturing runs and have
enough spares for repairs. So from the time it is introduced,
until the time that you have to either thoroughly
re-design your product - to use newer, available
components - or simply replace that prodcut with a
new-generation product entirely, you've got five years
or so. Then you have to support it for an additional five
years (unless it's aircraft, then you support for

So, those customers are using product that was designed and
documented two-to-five years ago. For the ones that
have a static installation - either they've bought and
installed all they need, or they routinely add more, but
only of a matching design/release vintage to what they
already have certified and deployed - that's usually not
a problem.
If there were any problems getting going, those were
encountered and solved with the help of our Support gang,
years ago... unless their market changes and they need to
adapt/modify what they do with our product.

Usually when Customer Support gets very specific doc-related
complaints, I get a ticket/issue in our system. When it's
more nebulous, I just get an e-mail or phone call (from
someone in Support or Sales Engineering) to explore
the possibility of some kind of change or improvement.
One of the biggest drivers of requests for new content or
new ways of presenting old content is new customers who
are using our product in ways we had not originally
anticipated, or coming from a market segment that we had
not considered. That's about par for a company making
products and toolkits for others to develop/integrate
their own solutions for eventual sale to their customers.

An example is that we get a request for a new feature
from one or two customers, and we implement it. I
document how it works in a framework of their line
of business. Then, somebody in a completely different
line of business discovers it and has a new way
to use it - either as-is or "if you'd just add this
little tweak...". But they're unsatisfied with the
way it's documented or that it doesn't use language
peculiar to their industry. Or, they are far less
savvy than the original customers and need a whole
new layer of hand-holding. Or...

I imagine it's slightly different in consumer products,
where next year's model is just a flashy increment
of this year's model, but ... as soon as you have
the new model nearly ready to hit manufacturing,
you _stop_ manufacturing the previous model.

You don't want them competing with each other,
as well as with the competitor offerings... which
are also "new".

It would be very different in industries where you
work with a partner or big customer on a project
for years.

It would also be very different in regulated industries
where standards dictate the content and the presentation
of much of your info.

In my industry corner, it's very rare for the doc-set
of a previous release to be updated. Docs get updated
when product gets updated. If there are errors or
omissions or later discoveries affecting older releases
of product, then the Release Notes get some additions.
The main docs are provided on CD or in tarball with
the original purchase, but the CRNs are available on
the company website for just that reason... update-ability.

As usual, this is known by a lot of you folks,
but newer writers might appreciate some insight into
how documentation is created and used in different
industries. Just doing my part and running off at
the keyboard.


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


Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial:

Explore CAREER options and paths related to Technical Writing,
learn to create SOFTWARE REQUIREMENTS documents, and
get tips on FUNCTIONAL SPECIFICATION best practices. Free at:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Re: AW: How do hiring companies view TW resumes?: From: Chris Despopoulos

Previous by Author: RE: Metrics (Re: How do hiring companies view TW resumes?)
Next by Author: RE: AW: How do hiring companies view TW resumes?
Previous by Thread: Re: AW: How do hiring companies view TW resumes?
Next by Thread: Re: AW: How do hiring companies view TW resumes?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads