Try the goddamned thing out
Try the goddamned thing out
OR,
some Thoughts
on Technical Writing,
having to do with
software writing
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.1
- 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 coding2, 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.
-
Or rather, you test it, then you figure out it doesn’t work the way it’s supposed to, then you ask the developer in charge of that ticket, then they say “oh yeah, that ticket doesn’t even cover it anymore, it’s this ticket now” and you open it and WOAH why is there a whole new feature being delivered through this ticket, I thought this sprint was just a patch release for that tiny bug they found that that customer complained about; ohh, it is going to be a SemVer patch release, they’re not going to bump up the version number because the customer isn’t ready to make a large upgrade, but they’re going to deliver three new API endpoints in this one and break three existing services, but that doesn’t matter because it’s only this customer who uses that thing anyway, and they’ll get their own custom config so there won’t be any problem. Anyway, then you describe it. ↩︎
-
This is why I believe that vibecoding is a useful tool for technical writers: potentially more useful than for software engineers. Software engineers have certain exigencies that LLMs may not help them with. The code may need to meet certain algorithmic requirements, or it may need to implement a particular architecture to be a good addition to the code base. LLMs are limited when helping here, but they’re really good at throwaway code: things you build once just to try something out. ↩︎