RE: most effective method for SME review?

Subject: RE: most effective method for SME review?
From: "David Artman" <david -at- davidartman -dot- com>
To: "Peter Neilson" <neilson -at- windstream -dot- net>, techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 23 Oct 2015 06:45:20 -0700

That's why knowing your product and docs is pretty critical: If you
don't know what's undone/changed, you can't find it to fix it; and so
you end up only documenting the new.

I don't think anything can avoid that, other than perhaps a
hyper-referential document structure in which you only document each
control once, in one place; and never cover conceptual or procedural
information; and never interrelate topics. That would, of course, leave
a lot to the user's own knowledge and experience: It's tantamount to
only providing a dictionary to an ESL student and expecting them to
write perfect prose.


Nothing can cure failure to communicate, especially if the product is
complex and the SME's change is subtle. It's a foolish company that
expects such failure to lead to good docs; and it's a poor SME that
doesn't communicate.


As for "only review the new", that what we do with PIs and a date range
on critdate:

* The REV value of the critdate is passed as an ANT argument.

* That REV is unique to a particular critdate (created or revised, no

* Only those PIs with dates that fall within the date range defined by
created and golive attributes are put into the change log.

Therefore, each development draft gets its own date range and, thus,
subset of PIs. When it time to put the doc out for release, we collapse
the critdates into one, comment out the development-draft critdates (to
maintain a record in the DITA file itself rather than only in VCS), and
pass that critdate's REV value to get the full change log for the whole

Short of a full CCMS with defined workflows that only call for
reviewing changed topics, I don't know how to make it easier.


-------- Original Message --------
Subject: Re: most effective method for SME review?
From: "Peter Neilson" <[1]neilson -at- windstream -dot- net>
Date: Thu, October 22, 2015 5:08 pm
To: [2]techwr-l -at- lists -dot- techwr-l -dot- com
On Thu, 22 Oct 2015 15:45:31 -0400, David Artman
<[3]david -at- davidartman -dot- com>
> ... info about what is changed on each change. ...
I've found that the problem with marking the changes is that nobody
catches the stale item you FAILED to change, and it's now wrong because
you left it alone. Worse, if only the SME knew that it changed, and
told you.
Nearly all SMEs and many other reviewers feel, "I don't want to see the
parts I reviewed last time. Show me only the new stuff."
No, I don't have a good solution for that problem.


1. mailto:neilson -at- windstream -dot- net
2. mailto:techwr-l -at- lists -dot- techwr-l -dot- com
3. mailto:david -at- davidartman -dot- com
Visit TechWhirl for the latest on content technology, content strategy and content development |


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-leave -at- lists -dot- techwr-l -dot- com

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

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Previous by Author: RE: most effective method for SME review?
Next by Author: RE: Into the Frying Pan
Previous by Thread: Re: most effective method for SME review?
Next by Thread: Translation management systems (TMS). Feedback sought about them

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

Sponsored Ads