The (not so) subtle art of technical writing
I’ve been asked questions about technical writing after my announcements (here and here) of pivoting to it as a full time job in February. Impostor syndrome aside, I didn’t (and still don’t) feel qualified to talk about it because it truly hasn't been all that long. But this blog has been about documenting my learning journey and that is what this post will do with the hope of shining light for other folks who want to make a similar transition or get into technical writing. Because guess what? This industry always needs more technical writers!
So let’s dive right in.
P.S. This is going to be in a QnA format because honestly speaking, I’ve spent a shorter time officially in this field and deem it better to draw from experience. Blogs have been written about what technical writing is, what it is not, and how to be a better writer so I’m not attempting to cover that. If you’re interested in such content, there are some resources linked below that you can check out.
Q#1: Can ANYONE be a technical writer?
Yes. There are no specific requirements in terms of the degree required or your background. I graduated in electronics engineering, worked as a systems engineer for 8 years, and led a team of 11 people before I pivoted to technical writing. However, as with every vocation there are skills required.
Q#2: What are the “skills” required?
It depends on the role you’re applying for. However, irrespective of the role, there will be a fair amount of editing and writing involved. Honing those two skills would be a good baseline for anyone looking to get started.
Additionally, the field is also moving towards a docs-as-code approach. This means using version control systems and tools such as static site generators rather than designing a documentation website from scratch. Git is one of the most popular and efficient version control systems out there, even though it doesn’t have a low entry level barrier and does take some getting used to. Some of the popular static site generators being used currently are Hugo, Docusaurus, Sphinx, Mkdocs. While a lot could be learned on-the-go, if you already do know them it could significantly improve your onboarding experience.
A lot of technical writing also involves explaining things in a simple manner. What this essentially boils down to is having firm foundational knowledge about the technology/tool/framework you’re writing and understanding different user perspectives. Having a systems engineering background, tinkering with my local install to figure out how a particular technology/tool works is how I choose to improve my understanding. However, I also supplement this with conversations with the project teams and the community since most of my work is in open source.
Last but not the least, some times technical writing may also involve a fair bit of UI/UX work. Again this would vary from role to role and there might even be separate teams handling this area.
Q#3: Is previous experience required?
This depends on the level of the role you’re applying for, the hiring manager, and the organisation the position is listed against.
Typically, some publicly visible work is required if you have not held a relevant title before.
Open source contributions or participating in one of the several outreach programmes (Google Season of Docs, Outreachy, LFX Mentorship) are great ways to demonstrate these skills and even though unintentionally this is how I, personally, built up a repertoire. I worked with CERN on Google Season of Docs revamping their documentation and also currently, co-chair documentation efforts for Kubernetes and LitmusChaos. Before co-chairing responsibilities came my way, I also contributed in various capacities within these projects.
Other ways to publicly showcase your work in a written medium, of course, are blogging or starting a newsletter.
Q#4: What does a typical day in the life of a technical writer look like?
There is no typical day, unfortunately, because it is largely autonomous work in my case and I can only speak what I’ve found from my experience and research. But I like to stay on track by writing content and reviewing content written by others every single day even if it is just rewriting a single paragraph in existing documentation.
This might seem idyllic and very close to the popular lone writer trope because how much effort could writing really be? Unfortunately this notion is wholly untrue and in most cases, individual research and A LOT of back and forth with various teams is required before a piece of content makes its way into the public eye.
Over and above this, I also do advocacy work in the form of conference sessions, podcast appearances, and content creation for this blog and the friday four newsletter. With this, I am able to tap into what the hive mind is thinking and am also afforded the opportunity to interact with the community.
Last but not the least, I read A LOT. Typical candidates include other projects’ documentation, my current projects’ documentation, newsletters, blogs, articles on popular publications, research theses, and whitepapers as part of my job. Sometimes I even cheat on podcasts by reading their transcripts because my attention span for listening/viewing content is very low. This is mostly to stay abreast of what is the newest in the ecosystem and also because I’m a huge nerd who voluntarily read nutritional information printed on the back of cereal boxes as a kid for fun.
Q#5: What does career progression look like as a technical writer?
As with most cases — whatever you want it to be. I know a few technical writers who continued rising up the ladder to lead a team of technical writers or become senior technical writers, ones who have assumed positions as directors of learning and advocacy, and few who have made their way back into an engineering role.
Q#6: Is it “less technical”?
No, IMHO. But I’d also go so far as to say that your answer to this would depend on what you consider technical.
To set some context, in my previous job I was a middleware administrator before assuming a people manager position. My job was to put out fires on a daily basis and troubleshoot systems while customers were impacted. I also did a fair share of infrastructure configuration & automation.
As a technical writer, I do not work on production outages anymore and definitely do not code or even write scripts on an everyday basis. However I still do have to figure out how a particular feature within a tool works via tinkering. This is, sometimes, even before the feature makes its way to the intended audience. In such cases, there’s no external reference I can draw comparisons to. Conversations with the project team and attempting to read the codebase myself is the only solution I’ve found to this issue.
So, that’s it for this post! Hopefully some of you found it useful and if there are any questions/comments that you’d like to ask, please shoot me a DM on Twitter/LinkedIn.
Resources:
