What I’ve Learned in a Year of Technical Writing
TL;DR: Ask lots of questions
In December of 2019, I graduated with my Bachelor’s of Science in Technical Communications from ASU. Bright-eyed and bushy-tailed (and so very ready to quit my job at Starbucks), I almost immediately stumbled into my first ever “real job”: a junior technical writer at a small SaaS company.
Three very short months later, lockdown hit and we all shuffled off to work from home. Like many others, our company had to adapt. And, like many others, my manager was let go.
A few months later, my more senior coworker got an offer in a different field.
Now “running” my technical writing department of two, I want to share what I’ve learned in the past year, and hopefully help someone out there who may be struggling as I did.
💡 Know What You Don’t Know
If you do not know how to ask the right question, you discover nothing.
–W. Edwards Denning
In technical writing, when so much of your content will be scrutinized by end-users who are probably already slightly miffed, it’s important to get everything right. When you’re tasked with writing content that might be a little more technical than you’re familiar with, recognize, and embrace your lack of knowledge — and find your subject matter expert (SME).
One important thing I’m still coming to terms with is that, as a technical writer, it isn’t your job to know everything about your product or problem. Your job is to get content from the steely trap of your SMEs mind to your end-user clearly and concisely.
Here are some of my favorite resources on interviewing SMEs:
- Mastering the Art of the SME Interview, TechWhirl
- How to Handle an Unresponsive SME, Medium
- Subject matter interview techniques for technical writers, HCi
Remember — your SMEs are people too, so just get to know them. Especially their preference for documentation review. Do they prefer Zoom meetings? Email chains? Back-to-back commenting on Google Docs?
Find out, and respect that.
And they’re busy, just like you. Value your SME’s time, always be prepared for your meetings, and make sure to ask the right questions.
🤔 Ask the Right Questions
If I had an hour to solve a problem and my life depended on the solution, I would spend the first 55 minutes determining the proper question to ask… for once I know the proper question, I could solve the problem in less than five minutes.
– Albert Einstein
While there are theoretically no stupid questions, some questions are better than others. Besides standard questions you should always ask when drafting documentation, here are some questions that I’m always asking:
- What is the timeline for this request? Getting in the habit of asking this as soon as someone requests anything from you will save you so much stress and hassle. It might seem obvious, but it’s something I often forgot early on, and then I was stuck tracking that person down on Slack or over Gmail. Knowing if they have an explicit date in mind will help you when juggling priorities, or allows you to nudge back.
- Who can I look to for technical questions? If your assignments always come from one person, they’ll likely know to tell you this. Regardless, always know who your SME is.
- Who can get me access to a test environment for this feature? If you’re documenting anything in which you don’t have access to the environment you’re supposed to be writing about… get access! Always test what you wrote, step-by-step, starting with your first draft. You’ll almost always find ways you can improve your instructions.
Some questions to ask your team (or yourself) are:
- Is this in the style guide? Reference your style guide religiously, and if you don’t have one, make one (Write the Docs has a great article on style guides). Whenever you’re considering using an ampersand or an “em” dash, double-check with your style guide. If anything is missing, determine what your process is for contributing to the style guide and get it added in.
- Do we have a template for this? Templates are a great time-saver, and they can help your documentation become more consistent. I’ve made templates for how-to articles, troubleshooting articles, and even GitHub README files.
- Is the process for this documented? It may seem like overkill when you’re working with a very small team, but documenting your processes will make life so much easier when: (A) Someone asks you to justify a decision or action, or (B) When a new team member joins and you find yourself repeating answers to questions you previously asked someone else.
📣 Speak Up, Speak Often
It’s part of the human condition to want to share things — thoughts, ideas, opinions.
– Paul Coelho
I’m adding this here because I’m still guilty of it: don’t be a passive meeting member. Technical writers — and writers in general — tend to have a different perspective than Product, Engineering, or Marketing teams.
If the idea of speaking up feels about as exciting as walking into a bear den covered in honey, start small. Show that you’re being an active listener by asking clarifying questions, or even just agreeing verbally where you previously would nod your head.
Once you’ve built up a rapport with your coworkers, you’ll feel more comfortable offering your opinion.
👍 Offer Help with Projects You’re Interested In
People seldom refuse help, if one offers it in the right way.
– A.C. Benson
Depending on your personality, this might feel uncomfortable, or a tad bit like overstepping. Remember: the worst thing your manager can say is “No”. In reality, most departments greatly benefit from the occasional help of a technical writer.
Notice the error messages in the new mobile application are kinda robotic? Offer to rewrite them. Hear that the Marketing team needs help writing content for a new product? Offer to write a draft.
The more hats you put on, the more you’ll learn, and the better your writing will become. To be successful in your career, you need to be proactive. Show you provide value beyond what’s being asked of you, and you’ll give everyone a better understanding of your talents and what you can contribute.
Caveat: Be mindful of your workload. If you don’t have the bandwidth then don’t offer.
📖 Don’t Stop Learning
Self-education is, I firmly believe, the only kind of education there is.
– Isaac Asimov
Continuing education is a make-or-break for your career.
Technical writing is a skill easy to learn, but difficult to master.
You start with many “aha” moments. These moments you can almost feel the sky open up and cast a dramatic ray of light on an understanding you’ve been vaguely grasping at for the past 3 hours.
But as time goes on these moments are fewer and far between. You know you’re not perfect, but you struggle to figure out what your writing is missing, or where a process can be smoothed along.
Here are some ways I keep current:
- Brush up on your writing skills. You could write the best documentation, but you write ‘affect’ instead of ‘effect’, it seriously undermines your credibility. Google has a thorough technical writing course that covers planning and authoring documents while giving a nice grammar refresher. And it’s free!
- Find and join a technical writing community. Write the Docs has a Slack community that I highly recommend joining and contributing to. There are also tons of LinkedIn groups, such as the Technical Writer Forum, or UX Writers. Regardless of your medium, finding a group of peers who are more than happy to be a sounding board can be a huge boon if you’re working with a small team.
- Analyze competitors’ documentation. Dedicate some time to analyze the help docs of your competitors. Are they worse or better than yours? If they’re better, in what way? Have a brainstorming session and answer: what can you do to improve your documentation right now, within a month, and within 6 months? Writing your thoughts down and developing both short and long-term battle plans can go a long way in improving the overall quality of your documentation.
- Take a non-technical writing course. While honing your writing skills is important, so is being well rounded. Check out courses on Udemy, Coursera, edX, or LinkedIn Learning.
Consider these focus areas for courses:
- Communication skills — focus on verbal. When most of your job is writing, you may not have the opportunity to polish your spoken communication.
- Project management — while likely the only projects you’ll be managing are your own, these courses can provide a breadth of knowledge on what may be happening on the other side of the curtain while giving you excellent tips on staying organized.
- Technology — variable based on your field. For example, in the software field, consider an API course.
Conclusion
TL;DR: Ask the right questions, keep improving, and don’t be afraid to branch out!
What lessons did you learn when you first started as a technical writer?
