This year I'm planning to attend the 2017 Write the Docs conference in Portland. The conference takes place May 14-16 and draws about 400 people who come together for three days 'to explore the art and science of documentation'. I'll be presenting a short talk on doc navigation best practices.
The following is a guest post from Michał Skowron and Jakub Wiśniewski, two technical writers working for 3di. 3di is a company providing technical authoring, translation and localization services. In this short review, Skowron and Wiśniewski evaluate MadCap Central, a new product from MadCap Software. MadCap Central is a cloud-based platform where you can host your MadCap Flare projects, manage builds, track tasks, manage users and their permissions, and collaborate with others. The article looks at the product from the perspective of a company delivering tech comm services.
Keeping pace with new technology and information is a core challenge for tech writers. You can divide the needed knowledge into four areas: product, technology, user, and industry domains. To limit the scope in each domain, filter by the users' tasks. To find time for the learning, implement morning routines for gathering information and log issues for needed documentation. Then as you work on the documentation and find yourself lacking knowledge, jump into online resources to learn what you need.
In this guest post, Derric Gilling, CEO at Moesif, explores various design choices for organizing API reference content in relation to the rest of your programming tutorials. He looks at three different strategies: (1) Centralized docs with separate API reference, (2) Centralized docs combined with API reference, and (3) Decentralized docs. The question of how to integrate API documentation into one seamless user experience -- particularly when you have auto-generated outputs of API reference topics from tools such as Swagger -- is a question that many technical writers regularly ask about.
I recently presented to the STC Twin Cities chapter on User-centered Design Principles for Organizing Documentation. When organizing your documentation, such as arranging navigation titles, workflows, or other wayfinding features, you can apply universal design principles to make your content more user centered. Some of these principles include Modularity, Hierarchy, Five hat racks, and Progressive disclosure. These design principles, based on solid user research from design gurus, will help users better find and navigate your help content. You can view the recording and audio from the event here.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
