New podcast from the Write the Docs community

The Write the Docs community now has a podcast available. The podcast follows a discussion-based format with several co-hosts talking about recent articles or topics related to tech comm. The podcast is available on almost every podcast platform. Read more »

Recording of Open Authoring -- Collaboration Across Disciplines presentation, by Ralph Squillace

Ralph Squillace, a senior content engineer for the Microsoft Azure Infrastructure team based in San Francisco, California, recently gave a presentation to the STC Silicon Valley chapter (on November 14, 2016) on Open Authoring -- Collaboration Across Disciplines. In the presentation, Ralph talks about Microsoft's approach to scaling their authoring and publishing efforts across the company by embracing Markdown, Github, open source tools, and other processes that allowed everyone in the company to write and contribute to Azure's documentation. Read more »

Review of Coding for Writers course by Peter Gruenbaum on Udemy

Peter Gruenbaum has a new course on Udemy called Coding for Writers. Overall, this course takes a unique angle in not only teaching you the basics of coding (in this case, mostly JavaScript and Java), but also teaching you how to document the code, such as focusing on parameters, responses, and data types. He even talks about style conventions in the documentation, including verb tenses, code formatting, and sentence structures. Read more »

Should you ever apologize for something product-related in your documentation? Looking at Apple's dongle documentation

Apple's recent dongle fiasco raises an interesting tech comm question: Is there ever a time when you, as a technical writer, should apologize for something product-related in your documentation? I looked at Apple's end-user docs about their ports but didn't see any acknowledgement that they were inconveniencing their users in an extreme way. Instead, the tone was merely straightforward and factual about which adapters you would need. When an issue is controversial or obviously of deep concern to users, documentation should address the issue head-on. You don't need to try to communicate about the issue in an emotional way (though that tone might be welcome to users), you just need to include the information, mostly following Reddish's documentation-as-conversation model. Read more »