How to design API documentation for opportunistic (active, experiential) learning styles
A recent study looked at how developers interact with API documentation. It found a mix of systematic and opportunistic learning styles. While we often write with the former in mind, focusing on the latter styles (opportunistic) might be more beneficial, and will cause us to focus on improving search, navigation, interactive components, troubleshooting, error messages, and other action-oriented features.
Confronting the fear of growing older when you're surrounded by young programmers
The engineering demographic can make even a relatively young person seem old. This sense of growing old is causing panic in many tech workers in Silicon Valley. One solution might be to change your mindset about what it means to be young, and to learn to unlearn what you have already internalized unconsciously.
Write the Docs Podcast Episode 20: Minimum requirements for good tech docs, with Matt Reiner
In episode 20, Matt Reiner from K15t joins us to talk about minimum standards for documentation — what techniques or standards can you put in place to help engineers and other contributors meet the minimum requirement for good tech docs? What essential sections, headings, or topics should you include in templates? And how do you help non-native speakers with grammar issues? We also discuss how tech writers can work with marketing to create honest and interesting writing. There seems to be the feeling that tech writing is dull but accurate and marketing copy is flashy and fluffy — we brainstorm ways technical writers can better align with marketing writers.
Corporate exodus narratives: A close look at the tension between the corporation and academia
Corporations often expect tech comm academics to fashion their curriculums to suit corporate needs; in contrast, academic departments want to give students a safe space free of corporate agendas for critical inquiry. Tech comm academics are often caught between these two groups and must satisfy both.
Recording and slides for my trends presentation at the Symposium for Communicating Complex Information (SCCI)
This week I traveled to Louisiana to attend the Symposium for Communicating Complex Information and presented on tech comm trends. You can listen to the recording, view my slides, and read my latest thoughts on trends here.
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.
subscribe via RSS