I just read this article and I’m wondering how accurate it is?
No. The article is misleading.
The author notes the move towards a UI – and excellent UIs depend on concise labels / help text.
If you don’t think much about it – you might think: “fewer words in the UI -> fewer writers”. I think that’s the mistake made by the article author.
I’ve been working on UI text for nearly a year – I’m finding that those fewer words in the UI require more time and a higher level of skill. In addition, the PoC for UI interactions is (frequently) some text configuration file, which requires explanation in docs.
On top of that, when you configure something via a UI, that action (or series of actions) configures just one system – to set up a repeatable process for a server farm / software cluster requires knowledge (and extensive documentation) of the underlying configuration files (or alternatively, the admin techniques to replicate such systems into appropriate clusters).
The outlook for technical writing in the US is for the industry to grow 10%, according to the Bureau of Labor.
I’ve noticed a decline in technical writing that is purely description and formatting, but a sharp increase in the need for software documentation at the level where the tech writer is at least partly their own SME.
However, at some point AI may get good enough to do some kinds of technical writing, as we’re seeing with auto-generated API docs now. That shouldn’t happen for a while, though - you’ll see self-driving trucks before tech writing is in danger.
This is all pretty encouraging. Thanks for the quick responses Mike and Sharon.
I think the article displays the common idea that “technical writing” = “technical manual writing”.
I would agree that the need for manuals is on the decline.
However, the need for technical communication is as strong as ever.
It just looks different than it did 5 years ago.
The article mentions UX as a career alternative, however, I think it might be better to characterize that as an example of how the field is expanding. TC has always been about being a customer advocate. Expressing that advocacy through user assistance is one way, but many of the facets of UX design do so as well. Moving TC toward UX or bringing UX into TC, it’s all the same. It just a reflection of progress.
I’ve seen several attempts at automatic API documentation generation and almost without exception, they’ve produced miserable to unusable documentation. However, research continues.
But, I think it’s looking down the wrong rabbit hole.
The challenge isn’t in the AI component (which would really need to read the minds of the developers who create the API and translate that into user-oriented text–a formidable challenge, indeed! ). The challenge to producing good software documentation is in the software design and development practices that go into creating the API. When those are solid, and include the notion that people will be the ones using them, the documentation effort is just one up from trivial. (Lots of research into what this requires–not lots of evidence that this research has been taken to heart, or worse, seen as providing any value). Where the documentation challenge exists is when the documentation is used to fill in the deficiencies of the API’s design. That’s where being a SME-level expert and a writer at the same time really pay off.
Cannot +10K this enough. Bob you read my mind and say All The Important Things. Succinctly. YESYESYES and then some more YES.
Did y’all get that? I agree with Bob?
Sorry, reply #3 here, but I want to comment on one part of what Bob says in a bit more detail:
“…when the documentation is used to fill in the deficiencies of the API’s design [is] where being a SME-level expert and a writer at the same time really pay off.”
Also if you can bring those sorts of skills to the table, you can work at pushing them into the design process. One of the beauties of API design as it’s currently understood (and by “understood” I refer to good design) is that it maps pretty nicely to the information architecture and naming skills that any good technical writer should either possess or be developing regardless of the product type they work on.
This is absolutely not to trivialize the hard work that goes into both design and documentation for APIs. And the closer you are to the developer mindset, the better the contributions you can make. But there’s a tendency among “traditionally trained” writers (that is, writer who come from a non-coding background and haven’t worked much if at all in or with code) to mystify APIs and their docs unnecessarily. And also, to a certain degree, to perpetuate a silo’d notion of docs, which is utterly the wrong way to go about API work.
(Guess I should go write another blog post on the subject … I had more words on the subject than I realized when I started ;))
I look forward to reading your blog post on this. (What’s your blog’s URL, BTW?)
I agree 100% with the idea, but I’ve never seen this happen in practice, at least with any degree of consistency. From my casual, non-scientific observations, I’ve seen these obstacles:
- Tech-comm input is brought into the process after the API has already become “baked” (i.e. it’s being used by others, making it very difficult to change).
- The goal of the API is, first and foremost, to get out there sooner than later to enable sales and adoption as soon as possible
- The marginal value of a usable API is not seen as being compelling enough to run the risk and marginal cost of additional engineering, design, and usability testing before launch.
- The technical writing force in a company is generally understaffed and overwhelmed with work to document things at the end of the development pipeline such that they have little time to devote to getting out in front of it.
#3 is often the result of #2 and #1. The marginal value is usually underestimated (and in most organizations, the downstream costs become someone else’s problem, e.g. Customer support, not Engineering) and the marginal cost is usually overestimated in terms of requiring additional engineering time and the resulting delays in releasing the API.
These might have been plausible reasons 10-15 years ago, but much research has been done in the past decade into how to make usable APIs. There are now many tools to prototype and user-test APIs making that faster and easier than ever. It is now much easier to do that before the actual engineering and coding of the API begins.
I would argue that demonstrating how you can help the engineering team model and usability-test an API before it’s committed to code would help make a more persuasive case to move technical writing influences further upstream.
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 …)
Despite the author’s decades of experience, he is missing what writers add to the mix–context. Of course the UI should be clear enough to not “make me think”, but how did the user get there and what are they going to do next?
Tutorials, user guides, recipes, what have you (and API references when appropriate) are where writers make their mark.