I'd Rather Be Writing - Tom Johnson

Write the Docs Podcast #3 - Trends for 2017

Fri, 03 Feb 2017 00:00:00 -0800

In this episode of the Write the Docs podcast, we discuss top technical writing trends for 2017. Chris Ward discusses how more technical writers are interacting with support groups, and even being embedded within support departments. Jared Morgan discusses how docs are being planned for earlier in development cycles, as more product managers are seeing the value of docs. I talk about how more technical writers are treating documentation as code, and the challenges inherent in developer tools and workflows. Read more >>

Technical Writing Trends and Predictions for 2017

Sat, 28 Jan 2017 00:00:00 -0800

My 2016 technical writing trends/predictions turned out to be pretty accurate. For 2017 technical writing trends, I'm predicting that more technical writers turn to Github in their documentation workflows. This trend applies mainly to companies where programming technical writers work with engineers to create developer documentation. Read more >>

Simplified Technical English and HyperSTE

Wed, 25 Jan 2017 00:00:00 -0800

Simplified Technical English (STE) is an approach to writing developed by the aerospace and defense industries to simplify technical documentation. STE consists of a dictionary of about 900 allowed words and a set of 65 writing rules. Together, this controlled language is formalized into a specification called ASD-STE100, which many regulatory industries must follow to ensure clear, consistent content. HyperSTE is a plugin offered by Etteplan to check your content for adherence to the rules and grammar of the ASD-STE100 specification. Read more >>

Recording: Modern Technical Writing, by Andrew Etter (STC Silicon Valley chapter)

Tue, 24 Jan 2017 00:00:00 -0800

Andrew Etter presented about his book, Modern Technical Writing, to the STC Silicon Valley chapter on January 24, 2017 in Santa Clara, California. In the presentation, Andrew talks about the strategies he implemented at Palantir to change to a new way of doing docs. This new way includes having a smaller team, using text editors, writing in plain text, processing pull requests instead of bugs, and more. He dives into lightweight markup syntax, static site generators, version control tools, and more, as well as challenges he has faced. Read more >>

Recording: Writing tech docs like a hacker with Jekyll

Wed, 18 Jan 2017 00:00:00 -0800

I recently gave a presentation titled Writing tech docs like a hacker with Jekyll to the to the Southern Ontario STC chapter (on Jan 18, 2017). In the presentation, I introduce reasons why we started using Jekyll, how static site generators differ from content management systems, how to get started with Jekyll, and challenges involved in using Jekyll for technical documentation sites. Read more >>

My top 3 posts of 2016 are all Swagger-related -- lessons learned from 2016 analytics

Tue, 17 Jan 2017 12:00:00 -0800

This past year the stats on my blog showed some surprising results. From about mid-2016 on through the present, there was a notably upward trend in page views. I attribute the upward trend primarily to some posts on Swagger. The larger trend is that all top posts on my site could be classified as documentation content. Read more >>

Swagger presentation recording -- Harnessing the Chi of Swagger in your REST API documentation

Tue, 17 Jan 2017 11:00:00 -0800

Recently I gave a presentation on Swagger as part of the TC Dojo webinar series. If you missed the presentation, you can view the Swagger recording here. Read more >>

FrameMaker and the mobile web: Evaluating Adobe FrameMaker's responsive HTML5 output

Mon, 16 Jan 2017 10:00:00 -0800

If you look at the surveys and other data collected about tool usage and priorities in the technical communication field, it's impossible not to acknowledge FrameMaker as one of the most common tools. Year after year it appears at the top of the charts, and print publishing remains a high priority. Although commonly known for its print publishing capabilities, FrameMaker also has an excellent responsive HTML5 web output. Getting responsive design right is difficult, particularly with documentation websites that have robust navigation sidebars. FrameMaker's responsive output is both mobile-friendly and impressively designed. Read more >>

MadCap Central -- a first look at MadCap’s new cloud-based collaboration and publishing solution

Mon, 16 Jan 2017 09:00:00 -0800

MadCap Central, recently released in early January, is a new cloud-based collaboration and publishing solution for tech docs from MadCap Software. MadCap Central allows you to configure and deploy Flare builds from a central server. You can also manage tasks, teams, users, and other details related to each of your projects in MadCap Central. Read more >>

How much code do you need to know to create API developer documentation?

Fri, 06 Jan 2017 10:00:00 -0800

With developer documentation roles, some level of coding is required. But you don't need to know as much as developers, and acquiring that deep technical knowledge will usually cost you expertise in other areas.

Attend my upcoming TC Dojo presentation on Swagger on Jan 9, 2017

Fri, 06 Jan 2017 09:00:00 -0800

I'm giving a TC Dojo presentation this Monday morning (Jan 9) on Swagger. If you're interested, you can register and attend for free. The event will also be recorded. Read more >>

TC Camp in Santa Clara to be held Jan 21, 2017

Fri, 06 Jan 2017 07:00:00 -0800

TC Camp is holding its annual free unconference for Tech Comm on Jan. 21 in Santa Clara. TC Camp starts with morning workshops given by experts in the field for a nominal fee. The unconference follows, where attendees vote on the topics to be discussed. It's a great event for networking and exchanging ideas, and I'll definitely be there. Read more >>

Generalist versus specialist: What should you focus on with knowledge building in your tech writing role?

Tue, 20 Dec 2016 00:00:00 -0800

I've been thinking about how I should focus my time with knowledge building in my tech writing career, especially given my context in a large organization. Lately, rather than primarily writing content, I've been playing more of a content curator / tools developer / publisher role. I'm okay with this. But sometimes I feel like I have to choose between acquiring deep technical knowledge versus acquiring deep tech doc tools/publishing knowledge. Read more >>

Write the Docs Podcast Episode 2 (which Focuses on Findability) Now Available

Sun, 18 Dec 2016 00:00:00 -0800

Episode 2 in the Write the Docs podcast is now available. The topic of episode 2 is findability: How do you allow your users to find what they're looking for in your documentation? We talk about various tools for findability: search, tags, faceted filters, sidebar navigation, inline links, related links, terms/glossaries, and breadcrumbs. In this post, I also share a few more details about Lunr search. Read more >>

Updating a single page versus updating the documentation as a whole

Wed, 14 Dec 2016 00:00:00 -0800

This past week I made some contributions to the Jekyll documentation, and in making the pull requests, I realized why technical writing is often so difficult. Making a request to one documentation topic often requires you to adjust other topics as well. So often we place the bar for contribution at whether someone can write. In reality, it's not just whether someone can construct clear, grammatically correct sentences. It's whether the person can integrate the information into a larger documentation set. Read more >>

New podcast from the Write the Docs community

Wed, 23 Nov 2016 00:00:00 -0800

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

Tue, 15 Nov 2016 00:00:00 -0800

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

Sun, 13 Nov 2016 00:00:00 -0800

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

Sun, 06 Nov 2016 00:00:00 -0700

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. Read more >>

How to avoid becoming extinct in your technical writing career

Sun, 06 Nov 2016 00:00:00 -0700

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. Read more >>