Scary responsibility in job ad

[Bill Swallow]

Agreed. I did this in a former role. We had a huge API/SDK that
required documentation. It would have taken 20 tech writers to meet
the target release date, as there were 40 engineers working non-stop
on it world-wide. So instead we added to the definition of "code
complete" a documentation item. Every class, method, property, etc.
needed to have documentation in the code for it. Upon check-in, both
QA and Docs would unleash hell on it to make sure it worked and the
element was well-documened.

Along with the code complete change, we also wrote up specific
instructions to feed the specs on exactly how things should be
documented. In the beginning we had some gems come by as
documentation. My favorite was "Microsoft made me do it." But with
some coaching and explanation, we soon had all engineers writing
pretty darn good documentation for the SDK/API. In fact, many caught
on to the point of it and loved documenting their code.

Best quote from an engineer: "This is great! I get to explain how what
I create applies to the whole of the product, and I can help
developers using this code to create some great application features!"
Yes, young padowan, that is the point. :)

The process was heavy on overhead at the beginning, but any new
process is as you ramp up. Many hours were spent in the first month
reviewing code docs, editing or punting back to the engineers, and
coaching them on what to write. But as the project went on, both the
writers and the engineers learned what to expect from each other (as a
group and individually), and we soon learned whose docs to pretty much
trust out of the gate and whose to pay special attention to.

The project was a success, as we documented over 12,000 elements
inside of 4 months, in addition to guides and such. We even
implemented the whole thing (guides, code reference and all) as a
complete context-sensitive Help system within Visual Studio (F1 on an
element to learn how to use it and see what works with it).

So yeah, not a scary or funny item to list in a job description. It's
actually very pertinent and applicable in many situations.

On Thu, Oct 6, 2011 at 6:52 PM, Combs, Richard
<richard.combs at polycom.com> wrote:
> Writer wrote:
>
>> A local company listed this as one of the responsibilities in a job ad
>> for a technical writer:
>>
>> "coach engineers to improve their writing skills"
>>
>> It makes me laugh and cringe in equal measures.
>
> I'm really surprised at the overwhelmingly negative reaction to this ad. Coaching engineers is cited as just one of the responsibilities; without seeing what the others are, I have no opinion of the ad as a whole, but this specific responsibility certainly doesn't make me laugh, cringe, fear for my future, or get defensive about my profession.

-- 
Bill Swallow

Twitter: @techcommdood
Blog: http://techcommdood.com
LinkedIn: http://www.linkedin.com/in/techcommdood