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.
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.
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).
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.
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.
On a recent trip to Claire's with my three girls, I saw a sign that captured the distinction between marketing writing and technical writing perfectly.
In early 2016 Google updated their search algorithm to reward sites with good content. I benefitted from this update and saw my blog's traffic jump up about 15,000 extra hits per month.
Tomorrow (June 23, 2016) the Write the Docs meetup group in San Francisco is holding a meetup focused on helping each other solve tech comm problems. The meetup theme is called Solve This!. If you're in the Bay area, definitely check it out.
I often hear tech writers in developer doc say they don't use a lot of visuals because users just want code samples. While code samples certainly connect well with users, there's also room to clarify difficult concepts through conceptual illustrations. The Android Vocabulary Glossary provides a perfect example of this.
A while ago, Cory Lebson, a seasoned user experience consultant, invited me to write a chapter on technical communication in part of his upcoming UX Careers Handbook. The book was just published and is now available for order. My chapter provides a detailed introduction to technical writing for any beginning trying to transition into this field.
Although the basic Markdown syntax can be pretty limiting, you can create more sophisticated HTML syntax and store it in templates. Using include syntax, you can pass parameters into these templates. This allows you to leverage more advanced HTML formatting (or other logic) without having to introduce the same level of complexity into your page authoring.
For more complex user process maps, you can group the associated topics into larger collections. When users click a workflow step, you can show them all the relevant topics within that collection. This approach accommodates a more complex user process workflow.
We're looking to add a couple of technical writers to our Appstore documentation team at Amazon in the Seattle and Sunnyvale locations. If you're interested, contact me. The focus is on developer documentation, so you'll need to be comfortable documenting web services.
