RE: This too is technical communication

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
>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
>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).

Emily Berk


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.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: Job outlook...
Next by Author: Re: This too is technical communication
Previous by Thread: RE: This too is technical communication
Next by Thread: Re: This too is technical communication

What this post helpful? Share it with friends and colleagues:

Sponsored Ads