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:techwr-l -at- lists -dot- techwr-l -dot- com Date:Thu, 07 Jun 2007 07:38:38 -0700
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
On Wed, 6 Jun 2007 15:41:38 -0700 (PDT), John Posada <jposada01 -at- yahoo -dot- com> wrote:
>... Any state of mind where you think of yourself as an idiot cannot be
>good.
>
>We don't gather information by being an idiot, by being clueless, or
>by being any combination of those terms.
>
>We gather information by being the complete opposite...with
>knowledge, with a thought-out approach, and with training.
>
>If you are taking the poisition of "Golly, Mr Developer...I'm just an
>idiot, so let me sit at your feet as you puke information on me.",
>then it is only chance if you get what you need.
>
>Instead, you should know what you are after and not complete the
>investigtion until it is clear.
>
>How do you know what to ask for when you don't know anything about
>it?
>
>That's why you hire experience...with experience comes that skill
>(and BTW...part of the answer is knowing something about the
>technology and knowing how to do research before meeting with the
>SME...put its only part of the answer).
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-
