Fabrizio Ferri-Benedetti recently published this post about failing as a technical writer. It’s raw and honest and made me think hard about how I operate as a writer of software (and now APIs).
Of all the points raised in his post, the one that hit me square between the eyeballs was the section entitled When we fail to raise docs awareness.
Now, I happen to work for a progressive organisation that actually values documentation. In fact, this has ramped up in the past 12 months because the senior leadership team decided to make documenting internal knowledge a priority. Up until April 2023, as the only tech writer in the company, my focus was always our end-user help that is embedded into our software products and UI labelling, messaging, and contributions to improve product design and usability. And now that we are creating more APIs to meet our customers’ data needs, I am also heavily involved in API docs.
Lucky me! I’ve been at my company for 10 years and my colleagues clearly understand and appreciate the value of the docs I produce. They know what a tech writer does. They know what my purpose is.
Or do they?
Why, only this week a senior developer with whom I collaborate on API docs thanked me for making our APIs better. My manager (also the company founder) recently praised me in my annual performance review for consistently meeting and exceeding expectations. People are always telling me that my docs make a difference.
So why do some people fail to understand the complexity of what I do? For example, the constant back and forth between me and SMEs to produce only a few pages of content. The complexity of the subject matter (payroll OMG). The hours sifting through often incoherent legacy content SMEs have insisted is ready for me to work with. The people who dismiss docs but fail to give me feedback on why they choose not to read it.
Fabrizio writes:
“One of the solutions, I believe, is to increase the visibility and respectability of our craft. I started this blog with the intention of providing writers with resources for the kind of discussions I described previously. I think technical writing, as one of the many faces of humanities in tech, deserves greater visibility. That can only happen if technical writers become prouder and more vocal about their craft.“
So maybe I need to educate people more about my craft. Maybe I need to explain to folks the nuances, the constraints, the opportunities. And perhaps I need to do all that with less side-eye and fewer scornful eye rolls. Less “no one gets me” and more “let me tell you how I can add value here”.
Thank you Fabrizio for your insights (and damn you for making me think so deeply on a Wednesday evening). 😒
Jody Winter 