In April, I had the privilege of sharing with you the day-in-the-life posts from four inspiring technical writers. To wrap up the series, I wanted to do something special. Which is why I made my very first day-in-my-life vlog! Here it is for your viewing pleasure:
Don’t forget to check out the day-in-the-life posts of our amazing guests:
Bart Leahy: Day in the life of a freelance technical writer (who previously worked at NASA and Disney)
Jason Tham: Life of a PhD student in Technical Communication
Swapnil Ogale: Day in the life of a contract technical writer in Australia
Larry Kunz: Day in the life of a technical writing veteran
Special announcement: There will be no post next week because I will be at the Write The Docs conference. However, I am planning to live-tweet the conference. Follow me on Twitter to keep up with the live updates!
The last post in this month’s series of guest posts is by Larry Kunz, a technical writing pro for 39 years! I have been a follower of Larry’s insightful blog for quite some time now, and it is an honor for me to have Larry share his perspective here on my blog. So let’s get to it! Here’s Larry’s post:
I’ve worked in technical writing, and in closely related fields, like project management or marketing, for almost 39 years. Today I’m a Lead Technical Writer at Extreme Networks.
We make and sell equipment for data networks — switches, routers, wireless access points — and the software that controls them. I write the documentation for installing, customizing, and maintaining the physical equipment.
You might’ve heard that technical writing is humdrum, that we do the same work day in and day out. That isn’t my experience.
One of the things I love about working in technical writing, in fact, is that every day is unique. We serve our employers and our customers in so many ways, and we use so many processes and tools, that every day presents new variety.
Let me show you what I mean, by stepping through a day in my life.
Knowing the technology
You might’ve heard that technical writers only need to know the basics of the technologies they work with. That isn’t my experience.
Today I’ll read the design specs for a new product the company hopes to introduce. I’ll read with two purposes in mind: to learn about the product, and to return comments to the designer if anything seems out of whack or is unclear. I might challenge the author to explain the app in terms that a customer would understand — to help me (and the customer I represent) understand how to use the app, not how the app works.
Working on teams
You might’ve heard that technical writing is a solitary profession — that you spend most of the time by yourself. That isn’t my experience.
Today I’ll meet with a software designer to get a big-picture understanding of a new app that customers will use to monitor our equipment. I’ll visit the hardware lab, where one of our test engineers will show me how our new switches are cabled together. In both cases, my colleague will help me gain the understanding I’ll need to describe our products to our customers.
You might’ve heard that technical writers aren’t respected by subject-matter experts, or accepted as colleagues. That isn’t my experience.
Today I’ll meet with three colleagues from Engineering, one from Tech Support, and one from Marketing to discuss a white paper I’m developing. This particular piece was inspired by something a customer wrote on the company’s user forum. It looked so good that I suggested touching it up and publishing it on the company website. But now, questions have arisen about whether its recommendations are in sync with the company’s overall marketing themes. I’m sure we’ll have a lively discussion, with each constituency being heard before I try to lead the group to consensus.
Solving problems creatively
You might’ve heard that technical writing isn’t a creative endeavor. That isn’t my experience.
Today I have to write instructions for mounting switches in a rack, when three different switch models come with three different mounting brackets. Some of the steps will be common to all three models, but some will vary. Making each step clear and not leaving anything out will require cleverness and imagination. It’ll require creativity.
Creativity is the art of solving problems, whether the problem is how to paint the creation of Adam on a curved surface (as it was for Michelangelo) or how to document the best way to mount three switch models with different mounting brackets. Don’t misunderstand: I’m not saying that I have even a tiny fraction of Michelangelo’s genius or talent. But I’m saying that he would recognize the creative process involved in doing the job of a technical writer.
A new day tomorrow
After a day of delving into technical details, of talking – and leading a conversation – with subject-matter experts, of solving problems creatively, I’ll rest up for tomorrow.
Tomorrow’s tasks will be different. I’ll post the final, approved version of a Hardware Configuration Guide. I’ll meet with the team that maintains the Confluence wiki we use to communicate throughout the Tech Pubs organization. Since I hold a senior-level position within my team, I’ll also be helping to rewrite the template our organization uses for documentation plans.
See what I mean? Every day is different. But every day makes use of my technical knowledge, every day has me working on teams, and every day gives me a chance to solve problems creatively.
Is technical writing the life for you?
Since January 2018, I have been blogging thrice a week about pursuing a Masters in Technical Communication, being a Technical Writer, and becoming “more technical”. However, all the posts were based solely on my experience, thereby providing only my limited perspective about the field of technical communication. I wanted to know more about others’ experiences and provide diverse perspectives on the blog. So I invited the technical communicators that I have admired and learned from over the years, to share their experiences on this blog, and they accepted my invitation!
Hence in April, I am tuning down the frequency of my posts from thrice a week to once a week to focus the spotlight on our guest bloggers each week. Here’s the schedule:
April 4: Bart Leahy – Former technical writer at NASA and Disney, currently freelancing. In his post, Bart gives us a sneak peek into the day-in-the-life of a freelancer juggling multiple projects.
April 11: Jason Tham – A student pursuing a Ph.D. in Technical Communication. In his post, Jason gives us an insight into the collaborative projects in technical communication across academia, service, research, and publishing.
April 18: Swapnil Ogale – A technical writer in Australia, Swapnil shares a day in his life as a contract technical writer in Australia.
April 25: Larry Kunz – A veteran technical writer with 30 years of experience, he is a treasurehouse of knowledge!
I am so excited to share their knowledge and insights with you! Stay tuned and don’t forget to subscribe.
Came across and liked this web architecture basics video, so that’s our Tech Byte for today!
After last week’s post about Docs FixIt Day at Cockroach Labs, I received several requests asking me to suggest open source projects that people can contribute docs to. As far as I know, almost all open source projects accept docs contributions. The following list includes some open source projects I find interesting:
- Mermaid (Docs: https://github.com/mermaidjs/mermaidjs.github.io)
- Typo 3 Documentation
- OpenStack Docs
- Microsoft Docs
If you have any favorite docs-friendly open source projects, tell me about them in the comments. And don’t forget to subscribe!
Update 1: Suggestions from the community:
Update 2: Came across this article: Open Source Maintainers Owe You Nothing, which I thought was a mandatory read for anyone who wants to contribute to open source projects. It is important to remember that developers and maintainers of open source projects usually work on these projects on their own time and dime, and it is not their responsibility to help us understand how the project works. We need to put in our own efforts, read all available documentation, learn about the project on our own, before we ask for their help.
As an engineer-turned-tech writer, I have repeatedly heard “Writing is so hard; how do you do it?” and “Anyone can write”. Both statements are fallacious. Yes, anyone can write, but not everyone can write well. And yes, writing is hard, and it is made harder by the romanticized notions of inspiration striking, wooden cabins in the middle of nowhere, and solitude.
In reality, writing is a methodical, multi-step process. In this blog post, I attempt to break down my technical writing process so as to demystify it and hopefully make you think about your own process. The following image depicts my writing workflow for any technical document:
As the image shows, my writing workflow consists of four phases:
Phase One: Research
My research phase consists of the following steps.
- Use the Cornell Note-taking System to briefly record the key points gathered from sources (reading materials, talking to engineers, attending meetings, and so on).
- Use the Feynman technique to ensure that you understand the information.
- Setup CockroachDB.
- Try out the feature being written about.
Phase Two: Draft
I use the 5-draft method while writing documents.
Phase Three: Editing and Reviews
Once I am satisfied with the rough draft, I edit my document using several techniques. Each technique helps uncover and correct different facets of the document:
- Grammarly: Check spelling, grammar, adherence to technical writing conventions
- Text-to-speech: I use the text-to-speech feature on my Macbook Pro to listen to the document. It helps me catch awkward sentence constructions, missing words, and so on.
- Elements of Style: This little book sits on my desk and reminds me of my personal pitfalls/repeated mistakes. I have earmarked the style guidelines that I know I forget. Going through the book helps me ensure I am not repeating my mistakes.
- Style guide: I go through the company style guide to ensure I adhered to it.
Once I am done self-editing, I open a Pull Request in GitHub which enables others to review my document. My review process is iterative, wherein my draft goes through technical and editorial reviews multiple times before it can be published. At Cockroach Labs, our engineers and other stakeholders (Product Managers, Sales, etc.) review the document for technical accuracy and completeness, and my manager and fellow technical writers review the document for editorial as well as technical completeness and correctness. The perks of working at a company that is deeply interested in good documentation 🙂
Phase Four: Publish
Once the reviews are done and everyone gives the LGTM (Looks Good To Me), it’s time to merge the document on GitHub and celebrate! Check out my Git profile here.
Try out the process, form your own, and share it with me at email@example.com. And don’t forget to subscribe!
Bonus: I track the various phases of each document in my bullet journal:
GitHub is a popular version control and collaboration. In my experience, learning GitHub can add tremendous value to your profile as a technical writer. GitHub enables you to contribute to open source projects and build your documentation profile. It also demonstrates your collaboration skills (working with developers and other team members), knowledge about version control, and overall technological literacy and comfort.
Getting started with GitHub is fairly easy. Follow the official guide to create your own repository!
And watch this video:
One of the life-changing books I have read in my professional life is Deep Work (affiliate link) by Dr. Cal Newport. As I discussed in the Day-In-The-Life blog post, I start my day with one-hour (2 Pomodoros) of Deep Work. And that has been the secret to my productivity and success as a technical writer.
Following are a couple of resources that summarize the book far better than I could have. Go through the resources, try out the technique, and drop me a line at firstname.lastname@example.org to let me know what you think of it. And don’t forget to subscribe!
Book summary: https://fourminutebooks.com/deep-work-summary/
I often imagine myself greeting my tech writing students as they graduate and enter the technical communication workplace. I imagine myself saying to them, “Welcome to the professional world. You have now graduated from being a tech writing student to a knowledge worker. And the key to succeeding in this role is not writing well, or being a good team player, but knowing what work to do.”
You see, in your days as a student, you knew what work was to be done that had pre-determined success metrics. You had set courses, with defined assignments and grading rubrics. You knew if your work was finished or not, and if you met the success criteria or not.
However, in the professional world, you will not be given a well-defined assignment. Instead, you will be given a “project” – a fluid, ever-changing best-guess scenarios developed by others in the organization. The success metrics are not defined either. As David Allen puts it, “There is usually no right answers; there are choices instead”.
As a technical writer, this is the part of the job I struggled with the most. With a never-ending stream of emails and Slack messages, changing roadmaps and company priorities, I was drowning in an information overload. I couldn’t get a handle on all the things that need to be done, let alone actually doing the tasks. At a time, I was juggling three highly technical projects that each required a considerable amount of brainpower and writes and rewrites. On the brink of a breakdown, I found David Allen’s Getting Things Done: The Art of Stress-Free Productivity (affiliate link). The book has been my savior. It has led to massive increase in my productivity and helped me maintain my sanity.
The Concept of Stress-Free Productivity
Anxiety quickly builds up when we begin to think about all the tasks we have to complete each day. It’s impossible to rely on our brains to remember it all! The Getting Things Done (GTD) strategy works on the premise of relieving our brains of the stress of remembering all that needs to be done by appropriately capturing everything in writing.
Capturing this information in what is dubbed our “external brain” allows us to be fully focused on what we’re doing in the present moment. This increases efficiency and creativity.
My GTD workflow
Develop the 4 Vital Habits for GTD Success
Applying GTD effectively requires more than just recording your to-do list. Making the GTD system truly work for you means embracing the following essential habits: capturing/collecting, daily processing, organizing, and weekly reviewing.
Capturing: Record ideas immediately. Keep notepads in places you frequent, make use of your smartphone’s virtual assistant (such as Siri or Cortona), or create a bullet journal. This helps your brain release the pressure of having to hold on to something to try to remember it. This ultimately releases your mental space so that you can focus on the present.
Daily Processing: Schedule time at the end of each day where you review each captured item and determine if you want to carry out the idea. If you do, you then need to determine the subsequent actions that must be taken. Actions that require extensive attention should be added to a project list.
Organizing: Actions that can be completed in 2 minutes or less should be further categorized into calendar lists, next actions lists, and follow-up lists. Calendar lists are for time-specific items. Next actions are important, but don’t need to be done within a specified time-frame. Follow-up list items are those that are dependent on additional information or actions from another individual.
Weekly Reviewing: Schedule about an hour at the end of each week to check the progress of your task completion. Reflect on where you see yourself in the next 3 to 5 years. Think about the projects and tasks that will help you accomplish that vision. Prioritize the action items that must be accomplished in the following week to make this vision real.
The GTD productivity strategy may seem like more work than you’re prepared to do. Hard work deserves a reward. Treat yourself to something you like at the end of your weekly review. The trick is that you can only effectively complete that weekly review to get the treat. Approaching your weekly review this way increases your motivation to get it done.
Bonus resource: An excellent YouTube video that discusses the GTD method:
So there you have it: the secret to my productivity and success as a technical writer. Next week, we will discuss another of my favorite productivity tools – the Pomodoro technique. Subscribe to stay tuned!