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.
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.
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 Redish's documentation-as-conversation model.
In contrast to other non-IT professions, the rapidly evolving pace of technology means that our experience a decade ago is practically obsolete. With new platforms, programming languages, workplace methodologies, and other changes coming on the tech scene every year, IT professionals must implement an approach of continual learning to survive.
Apple's new Macbook laptops include a Touch Bar that replaces the function keys at the top of the keyboard. You can program these keys with your own custom functions. I was curious to see what the documentation for the Touch Bar looked like. In looking at the Apple docs, the most interesting element is the image sizes -- the original image sizes are 4 times the size of the shown graphic. This technique helps create a sharp, crisp look to text when the large image is constrained to a smaller size in the browser. However, if you're translating your content, text callouts can be problematic.
In the deliberation about authoring formats -- whether to use Markdown or reStructuredText or DITA (or something else) -- one detail that is frequently overlooked is the importance of the accompanying tool or platform that uses that format. You almost never use these authoring formats alone but rather with a tool that stores, processes, and renders the source into an output. The tool you use with the authoring format is almost as important as the authoring format itself.
Recently MindTouch published a list of the top 25 Content Strategist Influencers. In contrast to previous top influencer lists, this year's list shifts from the term 'tech comm influencer' to 'content strategist influencer'. They also broadened their measures for determining influence, including less online presence and more offline influence, such as conference presentations. I just barely made the list this year. It got me thinking about whether I am in fact a content strategist or a technical writer.
In the latest episode of This Week in Tech (TWIT episode 585), the hosts talk about how confusing Apple's two-factor authentication is compared to Apple's two-step verification. The hosts, who are all tech gurus, had trouble sorting out the difference, and their experience with the service was even more problematic. This naming fail points to a core challenge in tech comm that happens when Marketing's choice of terms makes it difficult or impossible for tech writers to communicate plainly.
What would you do to rebuild trust in your brand after a product disaster like Samsung's exploding phones? I looked at Samsung's recall notice and newsroom articles to see what strategies they employed, but I found the communication brief, plain, and short of any detail that would help rekindle trust. If company's want to gain user trust, they must share more information and details with users, as Dyn did in their company blog posts after the recent DDoS attacks. Particularly, the information the company shares should align with the kind of information users want to see.
Although email may seem somewhat antiquated, it has by far the greatest reach of any online communication method. If you have a Jekyll-based site, here's an easy approach to sending out an email newsletter. This approach involves using a for loop to get a summary of your latest posts and then pushing the content into simple HTML formatting that you can paste into Tinyletter's email template.
Sidebar navigation is one of the more complex components of a documentation site, and it is critical for helping users understand and find documentation. I hacked together a sidebar menu for a doc site that's hosted on a somewhat inflexible platform, using Jekyll to generate the sidebar. Important features of a documentation sidebar include multiple levels of depth, expand/collapse options, accordion effects, fixed navigation, dynamic menu highlighting, and more.
Lately I've been turning my attention away from audio fiction and back into technology podcasts. I'm curious whether looking at the tech comm angle associated with technology news might provide a fruitful angle for blog posts and discussion.
In this presentation, Alisa Bonsignore, a technical communication consultant based in the San Francisco Bay area, talks about how she developed confidence and experience in consulting with clients about writing projects. In the beginning, Alisa started out by apologizing for projects in which she worked excessive numbers of hours for little pay, often trying to meet last-minute requests that required late nights and zapped her work-family balance. But project by project, she started to understand how to interact with clients in a more professional, self-respecting way. Ultimately this helped save her sanity and build a stable income through a reputable business.
Tools are an odd problem in tech comm. On the one hand, companies don't want you to spend hardly any time at all either learning or setting up authoring tools. Preferably, you should already be familiar with the company's tools before being hired. Then after you're hired, companies usually want you to focus on content, not any kind of tool configuration or setup. On the other hand, it seems like almost every company I've been at has needed extensive help with authoring/publishing tool setup and configuration. I am starting to think that my pattern of deep diving into tool sets at companies is indicative of a deeper interest in web development.
The Android documentation is one of the most interesting documentation sites I've seen. To appreciate the site, look at the left sidebar navigation. Not only does it expand and collapse vertically in accordion style, it also moves right and left horizontally into additional level hierarchies. The site authors have made a massive sidebar menu more navigable through JavaScript wizardry.
