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.
If it helps, suggest to the SME that the guide you are creating should be
targeted at poor-quality programmers, not for the SME himself/herself. With
good enough API documentation, people who know just some coding can create
good-enough applications too. (For example, if you are creating an API and
API docs that physicists will use, the physicist user may know programming,
but not be primarily a developer.)
Lois
On Tue, Aug 25, 2015 at 3:30 AM, Peter Neilson <neilson -at- windstream -dot- net>
wrote:
> [snip]
>
> There is a dilemma in writing API guides, because (1) the tech writer
> will--naturally--not be an expert programmer, and (2) the SME, an expert
> programmer, will deem the task of writing use cases for the API to be
> trivial, and will often produce hand-wavy and untested code. If you simply
> test the SME's example code, find it unusable, and ask the SME, "I don't
> see how this is supposed to work. Is it broken?" you may receive hostile
> insults to your competence. (Been there. Done that.)
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn more about Adobe Technical Communication Suite (2015 Release) | http://bit.ly/1FR7zNW
