Re: This too is technical communication

["Mike Starr" <mikestarr-techwr-l -at- writestarr -dot- com>]

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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.