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.
Since I've been working at Amazon, my tech comm role has shifted more to content curator and publisher than simply author. This shift in roles brings with it some new challenges and responsibilities. Some of the previous scrum methods with agile no longer seem to fit. I'm finding that kanban might align better with my workflow.
Last Monday we had a record turnout at our STC Silicon Valley chapter (with about 40 attendees). The topic was a panel discussion on how to thrive in agile environments as a technical writer. With 5 panelists all from different companies, the perspectives and practices they shared varied a bit, which showed the adaptations different writers and companies have made with agile to make the process work for them. This post contains a full description and recording of the event.
I recently published an article about Swagger in the Autumn 2016 edition of ISTC's magazine, Communicator. ISTC stands for Institute of Scientific and Technical Communicators. My article provides an introduction to using Swagger (now called OpenAPI specification) for publishing your REST API documentation.
Matt Ness, a technical writer at Splunk and a co-organizer for WTD San Francisco, recently gave a presentation to the STC Silicon Valley chapter called Let's Tell a Story: Scenario-Based Documentation. In this presentation, Matt talks about ways to integrate storytelling techniques into documentation, drawing upon his experience as a Dungeons and Dragons player and his player experience from other video game or fantasy worlds. To help users on their journeys and quests, you need a narrative to guide them and a manual to help them overcome obstacles. Video, slides, and audio from the presentation are included in this post.
Sometimes I think that I've covered every possible topic on this blog that is possible to write about, and my muse becomes silent for a while. But then I remember the purpose of the blog -- to be a web-based log, or journal -- and I realize that the only reason I wouldn't have anything to write about is if I stopped having experiences, stopped reflecting on those experiences, and ultimately became a zombie. That zombie state is the death of any career.
Ferry Vermeulen asked more than 70 tech comm pros -- from both the U.S and Europe -- what their 3 essential tools are. The combination of American and European responses makes for an interesting mix. While the majority of respondents listed either MadCap or XML tools, people also listed a variety of tools for working with images, prototypes, projects, and more. There were more than a dozen tools I'd never heard of. In this post, I highlighted some of the lesser known tools and also the responses that caught my attention as being unique, insightful, or otherwise interesting. Overall, it's fun to look through the profiles and see the diversity of people, tools, and specializations in the tech comm field.
Andrew Davis recently gave a presentation on finding developer documentation jobs (mostly for API documentation) in the San Francisco Bay area. The title of the presentation is Hunting for Dev Doc Work around the Bay. You can listen to the presentation recording, check out the slides, or just download the audio.
Translation is a complex undertaking that usually requires you to take advantage of dynamic variables and other parameters in your source format in order to generate out different languages. Although most people think of static site generators as containing static content only, it's actually only static output. During the build process, you can take advantage of these more dynamic characteristics to handle rules for outputting to different languages. In this post, I explain some of the details you have to account for (includes, links, images, re-used content, etc.) when managing a translation project using a static site generator such as Jekyll.
My previous post reviewing Andrew Etter's ebook on Modern Technical Writing got an enormous response. Some readers said the docs-as-code approach works only for small shops and doesn't scale to large projects. They said content re-use and translation also become problematic. However, perhaps the real differentiator shouldn't be product size as much as product category. The docs-as-code approach (which is what I'm calling it) works particularly well for developer documentation, such as API documentation, which usually doesn't contain the same challenges that component content management systems (or CCMSs) were meant to solve.
Up until two years ago, Anders Svensson and his colleagues, based in Sweden, provided DITA and XML consulting. They eventually created their own XML-based component content management system (CCMS) called Paligo, which includes a full set of documentation features to handle single-sourcing, translation, and other documentation needs. Paligo solves the challenges that Svensson's customers had been facing for years with other CCMS systems.
In Modern Technical Writing: An Introduction to Software Documentation, which is an e-book you can read on your Kindle, Andrew Etter argues for a model of technical writing that involves lightweight markup languages (like AsciiDoc and Markdown), static site generators (such as Sphinx), distributed version control systems (like Git or Bitbucket), constantly iterating/updating doc content on your website based on analytics, and more. Etter's book resonated with me because it articulates so many of the principles I've felt about how documentation should be.
Principles in Tim Ferriss' book The 4-Hour Work Week can be applied to tech comm projects. By focusing on the 20% of tasks that result in 80% of the results, limiting your focus to two mission critical tasks a day, empowering those around you to make decisions, and avoiding distractions from trivial tasks, meetings, and email, you can be much more productive in your work. More than crossing off a list of tasks, this approach will likely make your efforts matter.
At the last Write the Docs conference, Riona Macnamara, a tech writer working on internal developer documentation at Google, moderated a panel about transforming your documentation process. The panel consisted of four writers from various companies -- Balsamiq, Rackspace, Microsoft, and Twitter. The panelists talked about how they increased collaboration and openness in their company's doc culture by transforming their authoring and publishing processes. Most of these transformations involved adopting a 'docs as code' type approach, which seems to be a growing trend.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.