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
During the May WTD meetup, Ruthie Bendor, a web engineer, gave a presentation titled Move Fast And ... Document Things? Lessons learned in building documentation culture at a startup. This post contains the audio and video recording of her presentation.
Presentation recording: Two Great Teams that Work Great Together: Bridging the Gap Between Documentation and Support
At the May WTD meetup, Neal Kaplan gave a presentation titled Two Great Teams that Work Great Together: Bridging the Gap Between Documentation and Support. This post contains the audio and video recording of the presentation.
Recording of 'Move fast and ... document things,' by Ruthie Bendor at Write the Docs
We recently hosted a Write the Docs meetup in Redwood City with a couple of excellent presenters. A recording of Ruthie Bendor's presentation is below.
Recording of 'Two great teams that work great together: Bridging the gap between documentation and support,' by Neal Kaplan at Write the Docs
We recently hosted a Write the Docs meetup in Redwood City with a couple of excellent presenters. Below is the recording of Neal Kaplan's presentation. I also explain a bit about my new lapel mic and recording process.
Some post-STC Summit thoughts
I attended the 2016 STC Summit in Anaheim, California this year. This is a brief, rambling post that recaps some of my thoughts and experiences.
Slides for Writing Tech Docs Like a Hacker with Jekyll presentation
Here are the slides for my STC Summit 2016 talk on Writing Tech Docs Like a Hacker with Jekyll presentation. In this presentation, I introduce the tech comm conference attendees to Jekyll and how it can be used for authoring technical documentation. I'll try to demo a few of the tasks I describe.
Slides for Documenting REST APIs Workshop — 2016 STC Summit Anaheim, Calif.
How do you establish more context in a topic-based writing model?
I'm trying to come up with way of providing more context for users in documentation. Providing context is essential to helping users understand how all the various pieces fit together. Without context, the information becomes fragmented and seems unorganized, maybe even random. I've tried a couple of approaches to establishing context -- consolidating the information more while I draft it, and also putting maps with signposts throughout the content. I still have a ways to go to figure this out.