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.
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.
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.
I'll be giving an upcoming free webinar about trends on BrightTALK on January 15, 2019.
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.
If you're doing research on API documentation, Bob Watson's API Bibliography, listing more than 100 articles, can be a great starting point.
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.
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.
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 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.
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.
In this Write the Docs Podcast episode, we chat with Mark Baker about structured writing, specifically focusing on his new book Structured Writing: Rhetoric and Process. After introducing and defining structured writing, Mark explains the four domains you can add structure: media, document, subject, and management domains. He explains the advantages of working with structure in the subject domain, and why mixing structure across subject and document domains can be inefficient. We also chat about how structured writing connects with SEO and microformats on the semantic web, the limits of structure in Markdown formats, how to implement structure in linking, and more.
Last week during an internal writers conference at Amazon, Carla Johnson (co-author of the Experiences: 7th Era of Marketing and other books) gave a workshop that ostensibly was about how to create more persuasive pitches for change within an organization. But what resonated with me a bit more was the novel technique for brainstorming by transposing categories of experience, which despite my background in literature and writing, I had never encountered.
When giving an hour long presentation, about 15 slides is ideal. Although having fewer slides might make you panic about possibly forgetting what you want to say, in reality fewer slides gives you more flexibility to narrate your idea journey in a dynamic way. If you have too many slides, it locks you into a fixed, rigid structure that can actually make presenting harder. Additionally, a good essay is often the foundation for a good presentation because many of the rhetorical elements of an essay (the introduction, thesis, evidence, argument, etc.) are reflected in presentations as well.
Trends in technical communication can be hard to decipher, even when looking at data. But one underlying trend is that technology seems to be getting more specialized and complex. This trend toward specialization is driving up the value of technical knowledge, making it more prized than writing skills. To handle the complexity, technical writers must play increasingly collaborative roles with engineers to create documentation.
