Implementing Swagger in your API documentation -- My ISTC article
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.
Recording of Let's Tell a Story -- Scenario-Based Documentation, by Matt Ness (STC Silicon Valley Presentation)
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.
Balancing the never-ending list of documentation to write with your natural interests and passions
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.
The variety of tools tech comm professionals use
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.
Presentation recording: Hunting for API developer documentation jobs in the San Francisco Bay area, by Andrew Davis
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.
The complexities of translation and the need for dynamic variables in the build process
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.
Will the docs-as-code approach scale? Responding to comments on my Review of Modern Technical Writing
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.
The Story of Paligo: A new browser-based CCMS with all the features you'd ever want
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.
Review of Andrew Etter's ebook on Modern Technical Writing
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.
Applying Tim Ferriss' 4-hour work week rules to tech comm projects
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.
Thoughts on Transforming Documentation Processes presentation at WTD: Evaluating the trend to treat documentation as code
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.
Context switching and efficiency -- Kanban to the rescue?
In Become More Productive and Motivated, Mattias Sander provides a well-written overview of Lean, which is a strategy for eliminating waste and focusing more on customer value. What interests me most with Sander's discussion about Lean is context-switching and the subsequent strategy of Kanban, which uses cards to regulate flow. While these principles were developed in the context of Japanese car manufacturers (namely Toyota), they apply equally to the technical writer's world.
Why Programming Sucks and the fallacy of documentation in the context of code chaos
Yesterday on Write the Docs, someone shared an article titled Programming Sucks, by Peter Welch. More than just a developer monologue, this article seems to hit on universal truths about programming, so much so that the article has been translated into 10 languages and even has a professionally-read audio version on iTunes (which I bought for $2).
Thoughts on Documentation Avoidance for Programmers
This past week on the Write the Docs forum, there was a bit of discussion around a recent presentation titled Documentation Avoidance for Programmers. In the presentation, Peter Hilton lays out a series of tips on how programmers might get out of writing documentation.
How the Solve This! meetup format turned out -- plus some unachieved parallels with the Dead Poet Society
At a recent WTD meetup, we tried out a "Solve This!" format, which focused on open discussion around challenges people were facing. It worked all right. But with large groups, discussions tend to become dominated by vocal participants while shy participants retreat into their shells. I wanted to recreate a similar dynamic as a Dead Poet's Society type meetup, but now I realize that large groups make this dynamic nearly impossible. One alternative might be to regularly break up into smaller groups.