I dunno, Bob, if you write so eloquently and persuasively here I’m feeling a bit like a blog post might miss the mark! Your points are all very well taken (as always!), and I was in fact writing to a very specific set of attitudes in my previous answer to the thread, one that I didn’t make particularly clear. Namely: “traditional” tech writers (if there really are such critters) seem a bit wary of API docs, as though they required some sort of special secret handshake or training or other arcane ritual to enter into. Which I find a bit baffling. But then, I’ve spent the last ten years being alternately bemused, consumed, and entranced by the fact that this particular resolutely words/humanities/everything-NOT-STEM girl in fact has a crazy affinity for code. And not everybody is like me. Well, d’uh.
Not that code = APIs. But APIs are a great entry point for someone like me who’s fallen in love with coding. And I want to share the joy. (I also kinda have a crush on good OAuth implementations. Yeah, I have some issues ;))
But back to your original points. I’m writing now from a situation that may be more unusual than I quite appreciate in the moment. I can’t say too much until I check in with the Great Corporate Types, but suffice it to say for now that I work on a big API project where design comes first (specifically, Swagger definition), and writers are regularly invited to the design review table. Yes, really. I’ve been on the job for not quite six months, and already I’ve weighed in on all sorts of naming/ontology/taxonomy/design issues. The writers don’t yet work closely enough with engineering and QA on the implementation side, but we’re working on it. (At least we have access to the code, so we can always go digging. And we’re starting to think about common tests for QA scripts/sample code for docs.)
Your points are all valid, and I’ve worked in shops like what you describe, where even design let alone documentation is treated as an afterthought. But one of the reasons I took my present gig is because it offered the promise of doing things differently, including taking advantage of writer skills further up the development chain than “oh, we have a new property, guess we’d better document it. Somebody call the writer?” Things aren’t perfect by any means (I’m sure you can identify gaps here that I’d better not call out explicitly), but they do offer a lot of opportunity for anyone with (sort of) “traditional” writer skills to contribute way further up the design and development process.
Not quite sure atm what the threatened blog post will contain, but I guess it’ll be a follow-on to this one (where I already say some of the things I said in my previous reply, and also fail to address the how-do-you-make-it-happen question that you so rightly call out): http://www.yourmom.io/2014/11/why_apis_need_writers/ (which I wrote a lot longer ago than I realized … interesting …)