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
