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?
This is the first post in the guest post series announced previously. Today’s guest blogger is Bart Leahy, a freelance technical writer living in Orlando, Florida. His diverse career has included work for The Walt Disney Company, NASA, the Department of Defense, Nissan, small businesses, nonprofits, and the Science Cheerleaders. His blog, Heroic Technical Writing, discusses the business end of technical communication. I have been following Bart’s blog almost since the beginning of my career and have found his blog incredibly helpful. Here’s Bart:
One thing I’ve learned about the freelance life is that there is rarely such a thing as a “typical day,” especially when you have multiple clients.
I’ve had company in town for the past week or so. Before they arrived, I did my best to get ahead of the curve on work for my primary client so I could play in the theme parks. Company left Tuesday, however, bringing me back to reality supporting other customers.
So Tuesday’s “typical day” looked something like this:
I’ve been helping the Science Cheerleaders gear up for the USA Science and Engineering Festival (USASEF) in Washington, DC, next month. The Science Cheerleaders are current and former pro and college cheerleaders pursuing careers in science, technology, engineering, and math (STEM). Their presence at USASEF includes signing trading cards (akin to baseball cards) for the Festival attendees. My technical writing task was to review and update the personal information on the cheerleaders’ cards: name, team, degrees, reasons they chose STEM careers, etc. Once everyone has approved her personal info, that information is handed off to the graphic designer to make the cards. As the cards are created, I’ll do some back-and-forth editing before they go to the printer.
Another side job I have is journalism for a space industry news blog called Spaceflight Insider. In this case, I volunteered to write a story about NASA and other space agencies releasing a new set of standards for future space missions. Using the NASA press release as a starting point, I translated the Engineerish into English, explained what the standards meant, and incorporated relevant and links to related stories. Once I submit my story into the approval queue, one of the editors will review the story for clarity, style, mechanics, and technical accuracy (space fans/readers are notoriously meticulous about catching any error of fact or citation).
Lastly I checked in with another aerospace client, Advanced Space, who had two or three short proposals due Wednesday. I reviewed those Tuesday night until 10:30 or so and finished Wednesday morning before heading off to a mid-afternoon doctor’s appointment. On those proposals, I reviewed some highly technical content, mostly for grammar, spelling, and punctuation. However, because I’m familiar enough with the company’s content, they trust me to review it for general understanding/flow as well. When I find content or wording that appears confusing, I leave a comment in the margins of the Google Drive document for one of the engineers to handle. My primary business contacts are with the CEO for work assignments and the business manager for invoicing questions or issues.
In the midst of all that, I also wrote the first draft of this blog during the 7-8 p.m. hour.
I recently tried to set my office hours to a more regular 8 a.m. to 9 p.m. Eastern Time, but obviously reality sometimes causes those hours to shift. I can’t control what a “typical day” looks like, but I can at least try to enforce when that day happens, right? It’s important to do your work well when you get it, but it’s important to have a life, outside of work too. Good luck with that.
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.
Note: I had written the following article review as part of my Annotated Bibliography project during my graduate program.
Tham, J. C. K. (2016). Wearable Writing Enriching Student Peer Review With Point-of-View Video Feedback Using Google Glass. Journal of Technical Writing and Communication, 0047281616641923.
Tham’s article discusses a case study of using Google Glass in student peer review sessions. The article also discusses the benefits, challenges, and recommendations of incorporating the process in technical communication courses.
Tham presents an extensive overview of wearable technology and student peer review sessions. He then elaborates on his research methodology of participatory design. In participatory design research, the participants collaborate with the researcher to study the research topic. The study was conducted in three stages. In the first stage, Tham introduced the students to the concept of peer reviews using Google Glass and conducted a device orientation workshop. In the second stage, Tham collaborated with the students to determine the evaluation metrics for the study. In the third phase, Tham and the students used Google Glass to conduct four peer reviews. The first two peer reviews were experimental and the next two reviews were evaluative.
The data collected was triangulated: the data included the students’ narratives, exit survey responses, and Tham’s observations. Using Google Glass, students could track comments and editing suggestions through video recordings. Reviewers may indicate places in writing where revisions are recommended by snapping a picture or recording the suggestions in video. These images and videos could be sent to the respective writers after the review session. With Google Glass, the focus of review shifted from written critiques to spoken comments. Students would employ the think-aloud protocol when reviewing their peers’ drafts.
The students had mixed responses to the exercise. Students appreciated the first-person perspective video feedback helped them understand the reviewer’s thought process while providing feedback. They also found the feedback to be more detailed than written comments. But they found wearing the device physically uncomfortable, reported being distracted by their classmates’ simultaneously talking into their own devices, and felt unsure if they were doing the process right.
On analyzing the students’ responses and his own observations, Tham summarized that the use of Google Glass for student peer review sessions led to personable, unfiltered feedback, provided verbal and visual channels in reviewing, and captured the reviewer’s emotion. Tham also identified the potential challenges to implementing the process as procuring the wearables, connectivity and file sharing issues, technical and financial support, and getting familiar with the technology.
The study is a qualitative developmental study. It has credibility because the students could freely share their opinions, and Tham relied on his observations and not just the students’ self-reports. The study also has transferability because it was conducted in a real-world classroom scenario. Tham shares his course material with the audience, thereby providing material to replicate the study.
This week, I interrupt your regularly scheduled programming of technical writing techniques to brag about the incredible people I work with, who exemplify a company-wide culture of good documentation.
Let me give you some context: As most of you know, I work as a Senior Technical Writer at Cockroach Labs. For a major product release coming up in April, we had around 163 open issues to be documented for the release. Some of the issues were big-ticket items while a considerable number of issues were small but time-consuming fixes. It wasn’t humanly possible for our team of 4 technical writers to document all the issues before April. While brainstorming possible strategies to complete the documentation tasks, we thought of enlisting the help of our fellow Roachers* to contribute to our docs. The Engineering team had previously organized a successful Bugs FixIt Day, so we decided to replicate their model and announced a Docs FixIt Day.
We planned and prepped for days – announcing the Docs FixIt Day at the weekly team meeting, sorting through the issues and marking the ones we thought the engineers can take up, and of course arranging for snacks. Our fearless leader, Jesse Seldess, brought delicious Babka, and my fellow tech writer, Lauren, baked out-of-the-world, drool-worthy cookies.
We started the day with Jesse’s “Getting Started with Docs” presentation. He discussed the purpose of the FixIt Day, walked the engineers through the Docs toolset (GitHub and Jekyll), and announced the prizes – a Docs-team authored poem** and an Amazon gift card. The prizes would be given to the person who resolved the most Docs issues, and also to the person who resolved the Docs issue with the biggest impact.
We had 24 people in attendance for the kickoff session – in office as well as remotely. At the start of the day, we had 83 open issues marked as FixItDay. The participants included interns, engineers, engineering managers, and our CEO as well! They self-assigned the issues they wanted to work on and wrote docs all through the day till 6 PM. The last I checked on the day, we had 52 open PRs ! And people were contributing PRs even after that, so the final count might have been higher. (IMO, Jesse deserves an award for reviewing all the PRs).
To say the day was a success is an understatement. Not only did we get a big chunk of our documentation done, but the event also fostered cross-functional team collaboration. The engineers’ enthusiasm was infectious – they were totally invested and involved in the whole Docs process. We had given them the option of either working on the Docs end-to-end (as in they write, edit, revise the content), or just provide the raw content and the Docs team takes over the PR for them. But almost all engineers opted to complete the docs themselves, asking us for assistance with our GitHub process and SQL diagram generators and so on. This gave them a chance to understand the Docs toolset and they voluntarily helped us figure out how we can optimize the toolchain.
I have never been prouder to be a part of a company as I am now. As a technical writer, I am intensely aware of how big of an anomaly our company culture is. In most companies, docs are added as an afterthought and technical writers are considered a pesky annoyance. At Cockroach Labs, however, the importance of good, sound documentation is deeply ingrained in our DNA. And that is evident in all forms of documentation we produce – RFCs, user docs, training materials, or even meeting notes. That is also evident from the fact that we already have a team of 4 technical writers for a team of around 35-40 engineers, when it is not unheard of at other companies to have one technical writer for 120 engineers. It is a privilege to work at a company where people genuinely care about good documentation and are willing to do everything they can to ensure we maintain the quality documentation we have. And I am thankful to be a part of an immensely talented team that is rooted in our core values: “Aim High and Build to Last”.
You can check out the awesome work our team did for Docs FixIt Day here.
*Roachers n. People who work at Cockroach Labs
**Poems written to express our appreciation for our peers is a time-honored tradition at Cockroach Labs.
Thе Pоmоdоrо Tесhniԛuе iѕ a time mаnаgеmеnt mеthоd developed bу Frаnсеѕсо Cirillо in thе late 1980s.Thе tесhniԛuе uѕеѕ a timеr to break dоwn wоrk into 25-minute intеrvаlѕ, ѕераrаtеd bу 5-minute breaks. These intеrvаlѕ are nаmеd Pоmоdоrоѕ, thе plural in Engliѕh оf the Itаliаn word Pomodoro (tоmаtо), after the tоmаtо-ѕhареd kitchen timеr thаt Cirillо uѕеd аѕ a university ѕtudеnt.
The Pomodoro tесhniԛuе helps you асhiеvе the following:
- Imрrоvе efficiency
- Kеер away from diѕtrасtiоns and fосuѕ оn thе task аt hand
- Imрrоvе timе-ѕеnѕе
- Eliminаtе ѕtrеѕѕ burnоutѕ
- Assist in аnаlуzing timе taken fоr tаѕkѕ
Hоw thе Pоmоdоrо Tесhniԛuе wоrkѕ
Thе Pоmоdоrо Technique rеgulаtеѕ when to diligеntlу fосuѕ оn a tаѕk аnd whеn you ѕhоuld take a brеаthеr.
This tесhniԛuе iѕ centered аrоund brеаking your timе down into роmоdоri (one Pomodoro iѕ еԛuаl tо 25 minutеѕ). You lоg a ѕресifiс tаѕk уоu are going tо work on and thеn ѕрrint уоur wау thrоugh thаt роmоdоrо. Aftеr 25 minutes of dеdiсаtеd wоrk, the timеr gоеѕ off аnd уоu tаkе a nice 5-minute brеаk frоm your wоrk.
Once your brеаk is over, уоu ѕtаrt аnоthеr 25 minutе long Pomodoro. This new роmоdоrо саn be dedicated tо thе ѕаmе tаѕk аѕ bеfоrе (if уоu did not complete it during thе previous роmоdоrо) оr a new оnе. Aftеr every 4 роmоdоri (рlurаl fоr роmоdоrо), уоu саn tаkе a lоngеr break, if уоu would like (ѕuсh аѕ fоr 15 minutеѕ).
While уоu’rе wоrking уоur way thrоugh a роmоdоrо, уоu can temporally interrupt it for uр to 45 seconds, if need bе. If thе interruption lаѕt fоr longer thаn thаt, уоur dеdiсаtеd fосuѕ оn thе mаin tаѕk iѕ viewed to bе lоѕt, аnd thuѕ thе Pomodoro iѕ rеѕеt (having tо ѕtаrt over at 25 minutеѕ) again.
Thе dеfаultѕ of 25 minutеѕ реr роmоdоrо, 5 minutеѕ реr rеgulаr breaks, 15 minutеѕ реr lоngеr break, and 45 ѕесоndѕ реr intеrruрtiоn seem to wоrk wеll for me аnd most people I knоw whо’vе triеd thiѕ hаndу tесhniԛuе оut. Hоwеvеr, that said, thоѕе arbitrary аllоtmеntѕ оf timе саn bе сhаngеd dереnding оn уоu реrѕоnаl hаbitѕ and ѕсhеdulе, ѕо аѕ lоng as уоu consistently ѕtiсk with thе аllоtmеntѕ thаt уоu’vе lаid оut. Fоr example, ѕоmе реорlе may prefer to wоrk “in the zоnе” for 50 minutеѕ, аnd then tаkе a 10 minutе break.
Why the Pomodoro Technique works
It is common experience that we can focus on a given task only for a short period of time before we get distracted (or seek out distractions). The Pomodoro technique helps to quantify and manage those focus periods. If you know you have to work for just 25-minutes, and then you can surf the web or check Facebook guilt-free, you will be more inclined to put in those 25 minutes of focused work. And you can get a lot done with 25 minutes of focus!
This technique has been a game-changer for me in terms of my productivity. As I discussed in the Day-In-The-Life blog post, I start my workday with at least 2 Pomodoros of focused work (which is almost one hour), and then I am free for the rest of the day to attend meetings, do some mundane tasks, socialize, or just goof off, because I have done the most important tasks for the day already.
The Pоmоdоrо Tесhniԛuе fоrсеѕ me to think in tеrmѕ of асtiоnѕ that nееdѕ tо bе tаkеn in order tо еffесtivеlу gеt things dоnе. It also imроѕеѕ thаt I рriоritizе аnd dесidе whiсh асtiоn I’m gоing to work оn. By hеlрing tо limit my аttеntiоn ѕраn tо a ѕinglе activity, thiѕ tесhniԛuе аidеѕ me in ѕtауing focused (instead of hopping between a handful оf diffеrеnt tаѕkѕ аnd/оr diѕtrасtiоnѕ).
Rеviѕiting my dаilу Pomodoro lоgѕ highlights whеrе I spend my timе аnd hоw рrоduсtivе I was thrоughоut a given timе period.
I now think of my tasks in terms of thе number оf роmоdоri thаt a givеn tаѕk might rеԛuirе. I diѕсоvеred that еvеn сhаllеnging tаѕkѕ саn оftеn bе tаkеn care оf in a handful of pomodori ѕеѕѕiоnѕ.
Try out the technique and let me know if it works for you. Drop me an email at email@example.com. And don’t forget to subscribe!
P.S: Here’s my favorite Pomodoro playlist:
In the last post, we learned about how the internet works. This week, let’s build on that knowledge to learn about cloud computing. But before that, we need to discuss data centers:
Next, we need to understand virtualization:
Now we can learn about cloud computing:
Finally, let’s learn about two popular cloud computing platforms: Amazon Web Services (AWS) and DigitalOcean:
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!