Re: techwr-l digest: February 25, 2002
Subject: RE: He said...She said...He said...etc. (Was Re: What's A TW Got To DO To Get A Job Around Here?!)
From: "Ed Gregory" <ed -at- gregorynet -dot- net>
Date: Mon, 25 Feb 2002 08:00:28 -0600
X-Message-Number: 32
Aha! A chance to disagree with Andrew, who said:
<The "writing cycle" can be boiled down to a simple process (whee,
process!).
<1. Write
<2. Edit
<3. Publish
<Writing is the "beginning" point of a project.
Nay, Andrew. The beginning of the project is interviewing, researching,
whatever it takes to learn about the content and the intended audience. This
is what the technical writer does that goes beyond technical editing.
What does it matter, then, that some of the source material stemming from
that research is the scribbling of a SME?
Subject: RE: He said...She said...He said...etc. (Was Re: What's A TW Got-- To DO To Get A Job Around Here?!)
From: Annamarie Pluhar <apluhar -at- mindspring -dot- com>
Date: Mon, 25 Feb 2002 10:19:45 -0500
X-Message-Number: 34
Oh, I love this list. It's so provocative.
My partner works the way Andrew describes. He learns something
thoroughly and then writes about it. Period. As he says, that's
writing. (Mind you 5 years of Silicon Valley in the '80's burned him
out and it's taken 11 to even consider doing anything techie again.)
But I think the reason there has been discussion of this issue is
that there IS something between the "writing" and the "editing" as
Andrew describes it. As an instructional designer, I've worked on
creating training (which is it's own skill) with an abundance of
technical documents, PPT presentations, white papers and SME input.
I think that what I bring to the project is a high degree of smarts
with some technical understanding to judge what is relevant and
important to include in the training, and an ability to work with
SME's to that the content comes out right. It's not just writing -
there's judgement, listening and interpersonal skills that come into
play. And then there is organizing the information for a particular
purpose.
That's creating something that wasn't there before, isn't it?
I do agree that - especially in the present job market - developing a
niche of expertise is a survival strategy. Maybe that's why I
dreamed about doing work on ISO9000 standards, a return to my TQM
work of the '80's. ? !
.Annamarie
the "how much should a writer learn
about what they are writing about" point)
Subject: RE: Mere editing (Re: He said...She said...He said...etc.)
Date: Mon, 25 Feb 2002 15:40:15 -0500
X-Message-Number: 81
Keith Cronin said 'umbly:
>
> To me tech writing encapsulates everything it takes to get a manual or
> help system out the door.
>
> Researching, getting training, interviewing, writing, editing, posting
> rants on bulletin boards, creating and tweaking graphics, designing
> documents, etc. If I'm working with legacy docs it also means
> inheriting,
> maintaining, and (I hope) improving them. I never stopped to
> think of that
> as a particularly grand or menial function. Just part of the gig.
>
> I've never had the luxury of JUST writing. Or "merely"
> editing. Or working
> with a "mere" editor. What a luxury that sounds like!
(and Andrew Plato responds)
>Because it is impossible to write authoritatively and intelligently if you
don't understand the topic.<
(and to her comment below ...)
>However, there is also a great deal of economic pressure to make companies
(and
therefore tech pubs groups) leaner and meaner. Why have writers who don't
know
the topic, when there are plenty of writers who DO know the topic? It takes
longer to produce quality documentation if the writers don't understand what
they are documenting. Therefore, companies can save money and ultimately get
a
better manuals if they require writers to possess content knowledge.
(Andrew also responds)
<Reprocessing text from an SME isn't writing. That's clerical work. Writing
demands learning about something and then building a document from the
knowledge you have borrowed, gleaned, or gathered.>
SO, my simple point is (largely to Beth) no, we're NOT SMEs, but never be
afraid to try something new. It's gotten me through good time & bad, most of
my career.
Steve Gillespie
Subject: RE: He said...She said...He said...etc.
From: "CB Casper" <knowone -at- surfy -dot- net>
Date: Tue, 26 Feb 2002 23:33:39 +0400
X-Message-Number: 65
Subject: RE: He said...She said...He said...etc.
Another point not included on this enjoyable
discussion is that the TW is the advocate for
the reader. Not only do we have to have enough
technical expertise to write and edit the material
at hand, we also need the ability to step back
from our docs and view them from the user
perspective. This is a skill that is sorely
lacking in the vast majority of people, let alone
the technical experts, thus another reason for tech
writers.
Not only do we have to write with technical
expertise, we have to be able to read without
it, and recognize the difference. I believe
this is a skill that differentiates technical
writers from other writers.
(Oh no, I see another thread approaching . . . )
insert an appropriate quote from one of Anne
McCaffrey's Dragonsong SciFi books concerning
threads & flames here
We have to
be able to learn the intricacies of our subject, through materials and
individuals, and communicate that in a form readily accessible by our
potential (or planned) audience.
Of course, every project or assignment involves a "learning curve."
Otherwise, we'd just provide pro-forma documents based upon our portfolios
(?), wherein we simply change the terms or nouns to "fit" the current task.
------
And to organize the information, you do have to understand it.
Rose A. Wilcox
------
Bruce suggested, "The ability to sling a memorable
phrase or write grammatically is fairly common. The
ability to structure material is much rarer."
Subject: What then is the SME/TW functional relationship? (was Re: Theory vs. Practice (was: What's a TW etc...)
From: "Melody Akins" <melodyakins -at- hotmail -dot- com>
Date: Thu, 28 Feb 2002 07:51:55 -0600
X-Message-Number: 14
Hi!
In response to Michael Huggins' post, Bruce wrote (2-27) in clarification of
a point about how much subject matter knowledge a TW 'should' have:
>>>"However, in case it wasn't, I meant: enough knowledge that you're not
not dependent on SMEs to tell you if what you've written is complete or
technically accurate.
>>>Conversely, if you are heavily dependent on SMEs for this information and
make no effort to correct that dependency, that's coasting."
My comment: Of what use are Subject Matter Experts, then? If a SME is just
on the project as a 'consultant' and has no actual responsibility for the
product, then is the SME to be asked to review the product on 'final
approach' only? Ever?
If the TW has no requirement to submit the product for review by the SME,
then why is the SME on the project / development team in the first place?
Does the TW just check in with the SME if there are a few *minor* (who gets
to judge what is minor? The TW? The SME?) questions?
Just some questions.
Regards,
Melody
Subject: RE: What then is the SME/TW functional relationship? (was Re:-- The ory vs. Practice (was: What's a TW etc...)
From: "Wilcox, Rose (ZB5646)" <Rose -dot- Wilcox -at- pinnaclewest -dot- com>
Date: Thu, 28 Feb 2002 11:00:06 -0700
X-Message-Number: 63
<<My comment: Of what use are Subject Matter Experts, then? If a SME is
just
on the project as a 'consultant' and has no actual responsibility for the
product, then is the SME to be asked to review the product on 'final
approach' only? Ever?
>>
I do not think that was implied by the quote responded to. I haven't been
in this thread that much, but I tend to be more of a writer than editor by
the current definitions by nature (although my current job includes more
editing than writing, not my choice.) The ideal process with the TW/SME
relationship, by my lights, would look something like this:
Documentation need identified
- Could be by management, user, SME, or TW
Initially gathering info
- TW is responsible for, but interviews management, user, and SME to gather
info
Prepare doc plan
- TW based on info gathered and expertise as a writer, recommending outline
and presentation (ex., online/hardcopy) and planning for risks (ex., lack of
SME time, no working prototype, etc.)
Give feedback, approve doc plan
- iterative process participated in by management, SME, writer, and,
ideally, user
Write to approved doc plan
- using interview, previously created material, prototypes, code reading,
and so forth, the writer fills in the outline and creates to the
documentation submitting drafts based on a review plan outlined in the
previously approved content plan (which should have identified reviewers and
roles)
Reviewing
- reviews ideally (and life rarely has met my ideals) should include
"technical content", proofing/style (internal editor position or peer
reviews by other writers), and final stamp of approval reflecting content
ownership by management, SMEs and tech writing team
User Acceptance
- Ideally, the user will "test" the documentation before final approval and
can create defects or bug tracking against the document as well as the
product
Maintenance and Storage
- ideally, an organization will include processes for maintaining a document
as well as guarding its value with proper storage of all source files
<<
If the TW has no requirement to submit the product for review by the SME,
then why is the SME on the project / development team in the first place?
Does the TW just check in with the SME if there are a few *minor* (who gets
to judge what is minor? The TW? The SME?) questions?
>>
Why is there only one possible relationship between a SME and TW in the
first place? Why is it all "black and white"? Ideally, I own the content
for communication and the SME owns the content for accuracy. Ideally, I, as
a technical writer, know when my interpretation of the SMEs info (whether
obtained by written copy, in person interview, reading code, email
interview, etc.) is shaky. Ideally, the SME reads the information carefully
to determine whether or not my interpretation of the facts communicates
truth. Ideally, our team work creates quality.
As a person who cares passionately about the quality of my work, it behooves
me to understand the SMEs information to the best of my ability. If this
means that I need to study some background information on the subject
matter, I will do so. Ultimately, I cannot control the quality of the SMEs
review. (Many times, in real life, I can't even get a SMEs review, which is
a whole 'nother thread!) To ensure the highest quality, I will understand
the material to the best of my ability. In fact, it is part of what I love
about my career. I am a dilettante of knowledge but an expert in
communicating that knowledge. Being a contract technical writer has
afforded me glimpses into a number of technical subjects.
My relationships with my SME ideally a teamwork relationship where we work
together to ensure the highest quality of documentation. The ownership of
the document ideally is the team. I think of myself as the final owner of
documentation quality, which includes trying to get the best deal for the
document. This includes doing my part to be as educated as possible about
the content, but it also includes motivating and communicating with my SME
to get the best possible information and reviews from my SME.
In real life, I have SMEs that won't talk to me at all, SMEs that won't
review a document, management that doesn't care about the quality of
documents, and users who don't even know that good documentation is a
possibility. I have a lot of educating to do here, and change in this
organization takes years. In the meantime, I am still occasionally
producing documentation <wry grin>, and it behooves me to make it as good as
I can within the constraints I live within.
In real life, my relationship with the SME is constrained by corporate
culture and the personality, experiences, and proclivities of each
individual SME. In addition, there are some documents that I can write
without much SME input and review and be sure they are useful. So in that
case, the SME is only there "as needed". I have been writing for 18 years
and do know a bit about sumwhat. :-)
I don't know if that answers the question, but heck, it was fun writing it!
Rosie
you have to master content.
"You cannot, under any circumstances, produce
intelligent and useful documentation if you don't understand the content."
Andrew Plato
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
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.
Previous by Author:
RE: The Best TC/TW/TE Education...commentary
Next by Author:
Re: Word 2000 Repaginating all the time!
Previous by Thread:
RE: Lion's Share - the ultimate usage guide
Next by Thread:
widget for TCL html browser, or similar
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads