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: 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
matter).
* 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
release.
Short of a full CCMS with defined workflows that only call for
reviewing changed topics, I don't know how to make it easier.
David
-------- 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>
wrote:
> ... info about what is changed on each change. ...
I've found that the problem with marking the changes is that nobody
ever
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
never
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.
References
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 | http://techwhirl.com
