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.
OK, I'm about halfway through the beastie, and I fear my estimation boils
down to,--yuk. I disagree with the author on several points. I agree with
him on others. The things I agree with I usually think of as common sense
(granted, that's not too common). I think my problem with the paper is
that the tone conveys a negative perception of documentation in general,
even though he winds up recommending a higher level of documentation than
I've seen in "non-agile" docs for non-XP environments, and supports the
inclusion of dedicated personnel for the documentation.
Lets do the rebuttal section by section, and maybe I'll have a better
opinion of it by the end of the essay:
1. Critical Points -- I agree with some points, and believe others
depend on specific situations. I argue with the idea one should actively
pursue mediocre quality, and only update "when it hurts", especially when
the scope of such statements are not well-defined (how does one quantify
some of those?).
2. Models, Documents and Source Code -- I disagree with some of his
definitions here. Granted, they are close to the mark as long as they are
confined to XP environments, but I would argue that models are part of the
live system documentation. I also see "documentation" as including more
diverse and volatile entities than the author seems to believe at this
point.
3. Why Do People Document -- I believe he missed several points. He
does not address communication to an _internal_ group (he seems to assume
consistent real-time communication between team members, and doesn't
accommodate the possibility of human resources being brought in mid-stream,
or during a rush period...documentation can save programming time by
conveying information without requiring real-time interaction). He
apparently assumes the person writing the documentation will not be
dedicated to the task of documentation (see item 4). He blurs the edges of
docs as analytical tools vs. busywork (maybe a pet peeve of his?), although
he makes some good points about some of the motivations behind such
peripheral docs.
4. When Does a Model Become Permanent? -- Seems to be simply a verbose
debate over whether a model should be kept in the system doc set at all,
slanted toward the idea that it shouldn't be. A valid question, under
certain circumstances, but not all, and it doesn't seem to flow with the
rest of the essay,--it sticks out like a pet peeve.
5. What are the issues associated with Documentation? -- I partly
disagree with list item 1; yes, time spent explaining code isn't time spent
typing it in. However, "writing" code isn't just typing code, any more than
"writing" documentation is just typing it in. It includes analysis of
whether what you're doing is usable/functional. Some programmers use their
SME time to review and re-evaluate how they're doing something, using the
TW as a usability sounding board or "test user".
I disagree with his assessment in item 2, and think the 3rd approach
(SME and TW collaborating on docs) is best, because the TW can shape the
info. request (i.e. limit the query) to minimize the time the SME spends
funneling info. (ever get a bunch of raw info. from an SME that doesn't
really belong in any of the docs you are working on?), and you don't have
the "fire and forget it" problems the other two approaches encourage.
In item 3, I agree the documentation needs differ between the
development and maintenance phases, but isn't it more logical to develop
the post-implementation documentation _before_ it's needed (at which point
you're stuck improvising if you don't have the docs ready)? This ties into
Item 4.
Item 4 states the problems of whether to document during or after
development, but its recommended solution doesn't seem practical, since
there is usually no time between the end of development and the beginning
of implementation, at which point you need to actually use some of the
documentation (e.g., training, sometimes tech specs for troubleshooting).
I agree with the point of item #5, the "documentation in code or out
of the code" discussion, that documentation has a broader audience (I'd say
"duh", but apparently there are actually developers out there who don't
realize this).
I sort of agree with #6, except I see it more succinctly as
project-focused documentation versus system-focused documentation (as one
system may have many projects assoc. with it, and vice-versa); project docs
have a beginning and an end, whereas system docs are live, and may change
if the system changes. Treating one like the other courts headaches.
Item #7 is too apples-and-oranges to me: the purpose of the docs in
the example would not be the same (if it is, someone screwed up). He is
asserting that size/volume perceived as a negative measure of quality is a
fallacious assumption, but in designing docs specifically to avoid that
not-necessarily-so-common assumption he reinforces the idea that accurate
detailed docs _cannot_ be produced (which is what caused the fallacious
assumption in the first place). The real issue is one of proper scope for
the doc purpose. Brevity may be the soul of wit, but excluding detailed
information solely to avoid a suspicion of inaccuracy is impractical.
6. What Does it Mean to Travel Light? -- This addresses doc selection,
and I'll agree with the basic concept that you don't add unneccesary
work(i.e., diff. projects may require diff. doc sets).
7. When is a Document Agile? -- This section seems like a common sense
"what makes a good document" list. In the XP context, it is solid and
appropriate.
8. What Types of Documents Should You Create? -- Ironically, that list
includes more docs than I've seen non-XP groups use.
9. When Should You Update Documentation? -- I can't see how this is
different from the standard update expectations. It sounds like he's saying
only update a doc if the implementation of what it describes changes. His
"when it hurts" catchphrase implies something much different, and of a
lower quality/timeliness ratio.
10. Effective Documentation Handoffs -- IMO, if your docs are of good
quality, handoffs are easier than if your docs are of the "barely passing"
quality he seems to recommend.
11. Strategies for Increasing the Agility of Documentation -- Most of
these sound correct, but #7 I disagree with, because it can be physically
impossible, let alone painful to wait until the last minute. #8 and #10 may
be hard to implement, depending on the team dynamic and whether the
customers are confrontation-prone.
*shrug* I think my opinion's the same, still. His tone still bothers me,
and implies he doesn't value documentation much at all (he'd not do any
docs at all if he could get away with it). Some of the reasoning behind
certain basics are reasonably stated, though I don't know why he's so
heavily focused on the system model.
Just one more opinion onto the review-heap,
Shauna
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attention ForeHelp and Doc-to-Help Users! Upgrade your existing product to
RoboHelp for FREE, through January 15th. RoboHelp can import your existing
Help projects! Learn how else RoboHelp can benefit you. www.ehelp.com/techwr
---
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.
