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.
The difference between marketing writing and technical writing in one small sign
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.
A jump in Google traffic due to content quality?
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.
Attend the "Solve This!" Write the Docs Meetup tomorrow (June 23, 2016)
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.
Examples of visual communication in developer documentation with the Android Vocabulary Glossary
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.
My technical communication contribution to the UX Careers Handbook
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.
Advanced formatting with Markdown using Jekyll and Includes
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.
More complex user process maps in documentation systems
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.
Interested in working as a technical writer at Amazon?
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.
Examples of linear workflow user maps built with JS and CSS
Maps are an essential tool for helping users navigate unfamiliar territory. Providing maps to users is the 101 of visual communication — these maps helps guide through the overgrown documentation forest, especially when users are trying to complete procedures that require them to visit multiple pages, or take different paths through the [undergrowth] content. The map is as essential to end-users as it is to hikers on an unfamiliar trail.
8 image translation issues for tech doc — guest post by Jeanine Shepstone
The following is a guest post by Jeanine Shepstone. In this post, Jeanine talks about some of the issues technical writers face when translating images in technical documentation. She outlines the workflows for both text translation and image translation, and the challenges of extracting, translating, and merging text back into images. Image translation is certainly one of the most difficult aspects of tech comm, and for this reason many people avoid it and stick with text only.
11 images issues for tech doc systems — guest post by Jeanine Shepstone
The following is a guest post by Jeanine Shepstone. In this post, Jeanine talks about some of the issues that images present with tech docs. For example, sorting out references to the images, single sourcing re-used images, converting SVG image formats to ensure browser compatibility, and ensuring the right file size for optimal page loading are some of the challenges that tech writers face when working with images in tech docs.
Presentation recording: Move Fast And ... Document Things? Lessons learned in building documentation culture at a startup, by Ruthie Bendor
subscribe via RSS