Asserting your expertise as a SME in the workplace: Q&A with Jennifer Mallette and Megan Gehrke
In the workplace, why aren't technical writers recognized as SMEs with the same credibility and respect as engineering SMEs? Why do PMs and others often override the judgment of technical writers on matters of language and docs? This post explores the challenges that technical writers experience as SMEs in the workplace, and strategies they can implement for asserting their expertise. The format is a Q&A with authors of a CDQ article, with a survey at the end.
How to become a 10X technical writer in the workplace
How do you become a 10X technical writer in the workplace (10X means 10 times more efficient and productive than others)? In this post, I raise the question and then offer a few tips I try to follow: (1) Record your meetings with engineers, (2) Respond quickly to emails and messages, (3) Iterate on content with ever-expanding layers of reviewers, (4) Put some work back on those who request it, and (5) Learn to say no so you can focus on fewer projects with deeper engagement.
How to motivate users to provide feedback: Show that you're listening to their input
To encourage users to leave more feedback, add a contact email field on your feedback submission form. When you receive feedback, provide a quick response that shows you're listening and taking action on their input.
Write the Docs Podcast Episode 19: Static site generators, with Jessica Parsons
Jessica Parsons, a documentation engineer from Netlify, joins us for Episode 19 of the WTD Podcast. Jess recently conducted a Static Site Generator workshop at the Australian Write the Docs conference at Melbourne. In this episode, Jess illuminates the world of static site generators, comparing and contrasting Hugo, Jekyll, Sphinx, Gatsby, and others.
Recording of Trends presentation on The Content Wrangler BrightTALK channel
Yesterday I gave a presentation called Tech Comm Trends: Providing Value as a Generalist in a Sea of Specialists on The Content Wrangler BrightTALK channel. The recording is embedded below.
Site analytics from Jan 1 to Dec 31, 2018 -- are more engineers writing docs now?
Every year, when I re-examine my site analytics, I take the time to reflect on trends I’m seeing with traffic to my own site. Not necessarily industry trends, just trends about which topics are popular on my site. Based on these trends, I assess and re-evaluate some of my directions. This year, I found that the increase in traffic on my API documentation site (which accounts for 59% of my overall site traffic) suggests that more engineers are writing docs. This confirms my earlier predictions at the beginning of 2018 that specialization will drive more engineers to write API documentation, with technical writers playing more supporting editorial and publishing roles.
Employment and salary outlook for technical writers based on the 2017-2018 STC Salary Database
The 2017-2018 STC Salary Database was recently released, and the employment and salary levels for technical writers are looking really good — especially for some areas. 'San Jose-Sunnyvale-Santa Clara' (a Metropolitan Statistical Area or MSA) had a 34.5% increase in tech writer employment for 2017 and continued to be the highest-paying MSA for the fifth straight year in a row. In this post, I'll share a few highlights from the report.
The absolute worst that can happen in 2019, or, Imagining a dystopian corporatocracy emerge after a permanent government collapse
As we enter into 2019, it's fun to think about what's in store for the upcoming year. I've already written about tech comm trends ad nauseam this year, so I won't repeat the same arguments. (If you missed those posts, I argue for an increased emphasis on subject-matter familiarity as a requirement for tech writers to be competitive, which many would say, duh — of course.) Instead, I'd like to explore another, more entertaining angle: the absolute worst that can happen in 2019. We all love the dystopian imagination, so let's indulge it. Okay, let's go really overboard and think about the absolute worst series of events that could happen to us this year. After all, isn't it better to plan for the worst and hope for the best?
Is Premium Grammarly worth it for identifying style and grammar issues in tech docs?
I recently ran every page of my API doc site through Grammarly to identify and correct style and grammar issues. Grammarly provides a lot of valuable feedback that is worth considering as you edit your writing. However, the issues flagged are more helpful for conceptual and narrative information rather than for technical procedures, in part due to the restricted vocabulary, unique tech terms, and more frequent passive voice in tech docs. Also, data privacy issues probably prevent Grammarly from gaining more traction in the enterprise.
Research on code documentation -- when not to comment on code
In this post, I summarize the findings of an extensive research project about how developers at Google find and use code documentation. The research found that for simple code, sometimes developers prefer to read the code directly. However, for more complex code, developers consult documentation, often by looking in the formal class declarations for information they need; other times they look at comments in the implementation code. Besides the location of docs, the researchers also identify what type of answers and guidance developers want in code documentation.
Top 10 holiday gifts for technical writers
Wondering what to get the precious technical writer in your family or workplace for the holidays? Here are some gift ideas.
My podcast about writing with Ellis Pratt on Cherryleaf
I recently chatted with Ellis Pratt on his Cherryleaf podcast. The episode is called Podcast 49: Should you specialise? Interview with Tom Johnson. We chatted about a whole bunch of topics, not just the should you specialize question in the title. Topics include purposes for writing, the influence of blog and podcasts, long and short forms of content, evidence for trends, what employers are looking for in jobs, unicorn candidates, how to define yourself, and more. If you like podcasts, definitely listen to this one.
Recording for Menlo Park API documentation workshop now available -- and some thoughts on using cardioid versus omnidirectional microphones for recording
The recording for the full-day API workshop that I recently gave in Menlo Park, California, is now available. This recording provides more than 5 hours of instruction about writing API docs — for free. I also share some thoughts on cardioid versus omnidirectional microphones, and which is better in a workshop setting. The audio narration of this post switches around the microphones so you can hear the difference.
New post in Simplifying Complexity series -- Principle 11: Be both a generalist and specialist through your technical acuity
In my Simplifying Complexity series, I added a new post called, Principle 11: Be both a generalist and specialist through your technical acuity. I also recorded this essay as a narrated podcast.
My upcoming presentation and workshop at the 2019 STC Summit in Denver
I'll be giving an upcoming presentation and workshop at the STC Summit in Denver, Colorado, held May 5-8, 2018. My presentation is on trends and the dilemma between being a specialist or generalist; my workshop is on API documentation.
subscribe via RSS
