I'm a flip-flopper when it comes to collapsible sections. Sometimes I think they're great, and other times I think they're problematic. A while ago I converted nearly all of my help's subheadings into collapsible sections. I trend toward longer help pages, and the collapsible heading sections seemed like a natural way to provide a kind of clickable TOC. Readers could see up-front all the sections on the page and go directly to the section...
On January 25, 2014, there's an unconference coming up in San Jose, California called TC Camp. Here's the description: TC Camp is an Unconference focused on Technical Communications issues, skills, challenges, and the various applications used by technical communicators. The purpose of TC Camp is to provide a local bay area conference for technical communicators that is driven by the members of that community–writers, editors, designers,...
For several years I've shown ads in my sidebar using the WP125 ad plugin. But I think readers tend to become blind to website ads like this, so I decided to switch things up a bit. If you look in my Sponsors section, you'll see snippets of text beside each graphic. Sponsors also have control to update the text and images themselves. I patterned this model after a section I saw on Techwr-l called “Sponsored Posts.” I found myself drawn to ...
The following is a guest post by Steve Goldberg. Steve is a technical writer and Confluence administrator working for a software company in London, UK. You can follow him on Twitter at @bergeroflondon. This post is written in a personal capacity of the author and does not necessarily reflect the views of his employers. Atlassian's 2013 Summit saw the company announce a swathe of new features and updates for their products, namely Questio...
I was talking with a friend the other day when he mentioned that over the weekend he had crossed off a few items from his "bucket list." For this friend, those bucket items involved skydiving over the Pacific ocean and sleeping on the beach. (Well, those last two items are fictional, because I can't really write what the items were). But it got me thinking, what are the items on my bucket list? First, a bucket list is a list of achievemen...
How to organize reviews A reader asks the following: Do you have any advice on how a rapidly-growing documentation team--i.e., a team that's growing roughly in proportion to our company's burgeoning number of engineers and enterprise software products--should go about managing peer reviews of each other's work? I'm specifically interested in best practices on how to give, track, and manage peer review assignments. For example, is it best ...
I gave a presentation at the STC Berkeley chapter last week. It was a lively group, and people had a lot of insightful things to say. Here are a few comments various participants made. I want to highlight these assertions because I hear them so frequently. Videos are too tedious to watch -- I'd rather have the text that I can go right to. Users only go to help to search for a specific answer, so they want a short topic rather than having...
One of the Girl Scout badges we recently worked on was the Bug badge. This was one of the most fun badges because it involved trapping and observing all kinds of insects. We visited Rancho San Antonio park to make our bug exploration. Here are a few pictures. The kids are running like they're avoiding a mudslide or something, but really kids just like to be active outdoors. A great place to look for bugs is a dry riverbed, under the rocks. I...
Do you ever feel like your life is just like the movie Groundhog Day? In Groundhog Day, Bill Murray has the same experiences over and over again each day. No matter what he does, he wakes up and experiences the exact same people, places, and other events on a repeating day. He interacts differently at times, which creates different (and comical) results, but when he goes to bed at night and wakes up in the morning, the same day repeats. I...
Voiceover techniques 1.1 Finding a Conversational Voice in Video Tutorials 1.2 The Problem with Speaking Conversationally in Video Tutorials 1.3 Finding an acoustic environment (Voiceover) 1.4 Sounding natural (Voi...
Have you ever considered that technical writing is much, much simpler than we make it out to be? I think I learned the most important principles in preschool: Tell a story. Draw a picture. Make a conversation. Play a game. Go on a visit. Of course we have grown-up names for these same activities: story = Corporate narrative picture = Visual communication conversation = Vernacular writing style games = Gamification or engagement techni...
I gave a presentation titled "Why users can't find answers in help" to the Silicon Valley STC chapter yesterday. As promised, here's a recording of the presentation: Audio recording If you just want the audio, here it is: Your browser does not support the audio element. Download MP3 (right-click, then Save Link As) The audio file should also be on the podcast in iTunes. Presentation slides Here are links to the slides: PowerPoint ...
A reader recently asked, Hi Tom, Do you collect user guides, instruction booklets/leaflets, manuals etc that you think are a good example and use them for ideas and inspiration? Would you say this is a good practice to keep up for a professional technical writer? As an aspiring technical writer, I believe it is useful and really helps me with ideas to convey information. User Manuals of electronic tech gadgets: I always keep, even if I n...
I'm giving a presentation to the STC Silicon Valley chapter on October 21 titled "Why Users Can't Find Answers to Their Questions in Help Content." Here are the details: Date and Time Monday, October 21 6:00–7:00pm: social networking 7:00–8:00pm: my presentation Location Harry's Hofbrau 1909 El Camino Real Redwood City, CA 94063 (650) 366-3733 (There's a side room in this restaurant where we can meet.) Cost Free You don't hav...
From my recent survey on why users can't find answers in help, many users voted on the following reason: The answer is buried in a long page, but the user only spends 2 minutes max on a page scanning. (survey results) The page may be 1,500 words long, but the user spends just a few seconds quickly scanning the page and misses the answer. In an earlier post, I talked about using subheadings as a way to overcome the problem of page leng...
