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 at the same time
In my Simplifying Complexity series, I added a new post called, Principle 11: Be both a generalist and specialist at the same time. 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.
Upcoming BrightTALK webinar on trends -- January 15, 2019
I'll be giving an upcoming free webinar about trends on BrightTALK on January 15, 2019.
Write the Docs Podcast episode 18: Recap and thoughts on the WTD Australia 2018 conference
In episode 18 of the Write the Docs podcast, we discuss the recent Write the Docs Australia 2018 conference held in Melbourne, Australia. Jared was an emcee at the event and shares his inside perspective about what made the event so successful. We dive deep into the unconference format, how to instill the Write the Docs brand into the conference experience, how super volunteers can avoid burnout, what sessions stood out, and more. Also, Chris confesses that he has attended about 40 conferences this year, and explains a few reasons why.
Bibliography of API documentation articles
If you're doing research on API documentation, Bob Watson's API Bibliography, listing more than 100 articles, can be a great starting point.
How to avoid being a secretary for engineers
If we just see our task as documenting solutions that engineers have solved, it removes the creativity and critical thinking dimension from tech comm. The creative dimension in tech comm comes into play as we identify and solve tech comm challenges, such as devising ways to simplify complexity or otherwise improve the user experience.
I'd Rather Be Writing is now an Alexa Flash Briefing skill
Now you can listen to the latest narrated post on I'd Rather Be Writing as an Alexa Flash Briefing skill. This means you can listen to my audio content through your Echo device.
Upcoming full-day API documentation workshop in Menlo Park
I'm giving a full-day API documentation workshop on Nov 8, 2018, in Menlo Park, California, in coordination with Scott Abel (aka, The Content Wrangler). There are still a few open spots left in the workshop.
The Tell-Tale Project — Guest Post by Edgar Allan Poe, Technical Writer
The following is a guest post by Edgar Allen Poe. Poe completed many works of both fiction and nonfiction in his life, including 'The Raven', 'The Fall of the House of Usher', 'Eureka', and most famously, the 'Tell-Tale Heart'. Many are unaware that one of Poe's first jobs was as a technical writer. In this post, he explains some deep conflicts and challenges he had on one project, and how he overcame the challenges.
Preferring technical acuity over specialized knowledge
In the debate between being a specialist or generalist, there's also a third option: developing technical acuity. A person with a high degree of technical acuity has the technical mindset needed to understand and solve problems across a variety of technical domains. Given the ever growing number of technologies, developing technical acuity can be more advantageous, especially in technical writing contexts since technical writers work with a lot of different technologies.