Try the goddamned thing out

Technical writing is a truth-seeking process.

To say true things, you need to know the subject that you’re writing about.

A technical writer is therefore more of an engineer who focuses on explaining things instead of building them. The writing is a secondary activity.

As a technical writer, you test each instruction that you write:

• In software, that means that you try that API call that you described. Or rather, you first try it, and then describe it.¹
• In motorcycles, that means that you work on a bike following your own instructions.
• In appliances, that means that you assemble the appliance yourself, before allowing it to be shipped off with nonsensical instructions.

(Or at least this is how it should be.)

In project management, there’s a belief that you can manage anything by simply applying universal tenets of project management. There’s an idea that you can be a project-agnostic project manager.

Technical writing, as a profession, suffers from the same problem that project managers have: there’s a belief that there’s a skill of “technical writing” which can be applied to many different things, regardless of what the thing itself is.

There is in fact a common, universal, set of skills a technical writer needs to have. This belief is not entirely false. But there’s also subject-matter expertise which is at least as important, if not more important, than universal technical writing skills.

This is why, sometimes, even badly formatted, grammatically incorrect and haphazardly written instructions from a developer are more useful than beautifully structured, diataxis-approved, vale-linted, Docusaurus-built docs from a technical writer.

The key thing is: is it useful? Does it help me, the intended user, to achieve my goal?

After you get to a certain level of proficiency in written communication, the only way that you improve as a technical writer is by focusing on the technical, and not on the writer part of your role.

The manuals written by professionals in previous decades were also very different than today’s. They were written by engineers who were generally also mechanics and craftsmen, and it shows. […] The writers of modern manuals are neither mechanics nor engineers but rather technical writers. This is a profession that is institutionalized on the assumption that it has its own principles that can be mastered without the writer being immersed in any particular problem; it is universal rather than situated. Technical writers know that, but they don’t know how.

Shop Class as Soulcraft, M. B. Crawford

In the context of software technical writing, this means that you should be a developer who integrates the SDK, who calls the API, or an end user who clicks in the UI, or… whoever your target audience is, you need to be that person, at least for a little while, at your own job.

You need to be coding², and building, and testing, and integrating, and making small apps, and trying to push to registries, and trying to apply configs, and just… doing all the things that your (technical) users are doing. If you’re not doing it with them, or much better, before them, then you’re not going to be helpful, your instructions are not going to be helpful, you won’t have that kind of situated knowledge that is useful and necessary. You’ll be divorced from your end user, and they’ll be left trying to piece together something based on your instructions. So you owe it both to yourself, as a professional, and to the end users you’re serving, to try the goddamned thing out.