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: This too is technical communication From:Emily Berk <emily -at- armadillosoft -dot- com> To:"Mike Starr" <mike -at- writestarr -dot- com>,<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 07 Jun 2007 09:02:35 -0700
After that initial discussion, yes, the original document made a WHOLE lot more sense to me.
I still had questions, but they were restricted to ones like "Is this still the case?" or "We don't want to share this with external developers, right?"
-- Emily
At 10:11 AM 6/7/2007 -0500, Mike Starr wrote:
>Those are just the sorts of situations I've been talking about.
>
>What I would like to know is, after your discussion with the SME, did the original document make sense or was it still gobbledygook?
>
>Mike
>--
>Mike Starr WriteStarr Information Services
>Technical Writer - Online Help Developer - Website developer
>Graphic Designer - Desktop Publisher - MS Office Expert
>Phone: (262) 694-1028 - Tollfree: (877) 892-1028 - Fax:(262) 697-6334
>Email: mike -at- writestarr -dot- com - Web: http://www.writestarr.com
>
>----- Original Message -----
>From: "Emily Berk" <emily -at- armadillosoft -dot- com>
>To: <techwr-l -at- lists -dot- techwr-l -dot- com>
>Sent: Thursday, June 07, 2007 9:38 AM
>Subject: RE: This too is technical communication
>
>>The question is when does the writer cry uncle and admit that she understands just about nothing of all the source materials she's looked at and can't even imagine where to start.
>>
>>I have a degree in comp. sci., worked as a programmer/software architect for 15 years (still do a lot of Web development), was an early adopter of C, OOPS, Java, C++, PHP, and quite a few languages and techniques most people are too young to have heard of, and yet ....
>>
>>Sometimes the available background materials are so -- scanty -- that I can only tell my SME that they need to start from the ground up and spoon feed me the information I need. IMO, this does not make me an idiot, and I would never tell anyone that I am one, but I do need to explicitly tell the SME that I lack the background necessary to write the doc and I need help in obtaining that information.
>>
>>For example, in one of my first projects at the company I've been at for a while now, the ONLY available background material was a year-old architectural specification. When I read this spec, it was literally the case that I could not parse a single sentence. It was littered with acronyms and I googled every one of them, but the acronyms were being used in ways other than Internet thought they should be. I read that spec at least 10 times, with my agitation growing every time, before my initial meeting with the SME. And I continued to get very little out of it.
>>
>>I knew that since the spec was an internal doc, and I needed to figure out how to translate this information for an external developer audience, I needed to understand what parts of the spec were not for external eyes. And because the doc was old and only a spec, there would be many things that would need to be updated to reflect how the product was actually implemented.
>>
>>This would have been impossible for me to do given my inability to understand nearly every sentence.
>>
>>I had never worked with the SME before and was very concerned that he might assume that I was unqualified to write the developer docs. But there was nothing for me to do except to lay out my inadequacies to the SME and beg him to explain "everything" to me as if I were a rank beginner. Because if I'd let him assume that I understood ANYTHING in that spec, there would have been no way for me to understand any additional knowledge he might want to add.
>>
>>So what I did in our initial discussion was to lay out my qualifications, and then, I said, "J., I do not understand a WORD of what is in this specification. You are going to have to give me a basic understanding of what this is all about." And, in about half an hour he did.
>>
>>So, anyway, I think we all need to admit our ignorance sometimes. The question is, how do we do that in such as way as to signal that we have the ABILITY to learn what's necessary, we simply lack the background to figure it out on our own.
>>
>>-- Emily
>
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
