The Tech Comm Manifesto
My life in technical communication would be much easier if we all subscribed to these rules:
Interview with a vampire: interviewing to find processes that drain efficiency
When you’re considering an overhaul of your publishing workflow, you may find yourself becoming a metaphorical version of Van Helsing, the vampire-hunting character from Bram Stoker’s Dracula (and the many, many movies based on the Dracula story). You need to find all the efficiency-draining aspects of your current process and eliminate them.
Trends in technical communication webcast
After some “interesting” technical challenges, the recording of our Trends in technical communication webcast is now available on Slideshare:
Webcast: Trends in technical communication for 2010
Sarah O’Keefe, Ellis Pratt of Cherryleaf, and Tony Self of Hyperwrite
Find out where these three presenters see the industry going. This event is for managers with tech comm responsibility, with or without prior technical writing experience.
The state of structure in technical communication
In early 2009, Scriptorium Publishing conducted a survey to measure how and why technical communicators are adopting structured authoring.
But will it blend?
In choral music, “blend” refers to bringing together a diverse group of voices into a pleasing sound in which no single voice is dominant. As technical communication moves into a more collaborative approach to content, it occurs to me that both writers and musicians need to blend. Here are some choral archetypes and their writerly equivalents:
- Soloists—singers with big, powerful voices or writers with distinctive styles—are a challenge to blend. The singers must reduce their volume to match the voices around them and sing the music without adding ornamentation. Writers must refrain from their favorite distracting rhetorical flourishes.
- Section anchors—journeyman singers who know their parts cold and provide support to others singing the same part. Section anchors may not have the vocal quality of a soloist, but they are competent singers who are always on pitch, learn the music quickly, and follow the director. On the writing side, this is a person who writes competently, knows the product being documented, always follows the style guide, and learns quickly. In a writing group, these may be the team leaders. They are not necessarily the flashiest or the most gifted writers, but their content ranges from acceptable to excellent.
- Supporting players—these singers lack confidence, but can learn their part and sing it, provided that they have support from a section anchor. Left to their own devices, they may drift off into another part (usually abandoning harmony to sing the melody line). But as long as someone nearby is singing their part with them, they can stay on pitch and contribute their voices. This equates to writers, often with less experience, who need support, encouragement, and editing to stay within the style guide. They need help in most aspects of the content creation process. Over time, supporting players can improve and grow into more confident section anchors both in writing and in singing.
- Blissfully tone deaf—Fortunately, many people who are tone deaf (or simply cannot write) are aware of their limitation. But if you’ve spent any time at all in a volunteer choir, you’ve probably experienced people who make up for their lack of pitch by singing louder. In a writing context, your best bet for the tone-deaf (short of a new job!) is to give them assignments that minimize actual writing, such as creating basic reference information (not a lot of room to maneuver).
Our challenge, as writers, is that we have been accustomed to working solo, and now we must learn to blend our authorial voice into the larger group. The skills that make great soloists are not the same skills that make great contributors.
Some Friday fun: tech writing in movies
Here’s a movie montage I found on YouTube featuring scenes of characters either offering or reading procedures:
Enjoy!
WritersUA: Wireframing tools and techniques
Michael Hughes, IBM ISS Security Systems
Yay, I finally get into a session.
Wireframes can be high fidelity (rendered dialog box that looks like the real thing) or low fidelity (sketch on a bar napkin). Fidelity actually has several components: appearance, medium, and interactivity.
Low fidelity appearance is something that looks (or is) hand drawn. High fidelity looks like a finished UI. Low fidelity appearance can be advantageous because people don’t get distracted.
Low fidelity medium is paper; high fidelity medium is an actual user interface.
Low fidelity interactivity is static—a picture of the thing. Then, you have scripted interactivity, where you take people through a scripted, controlled sequence. Next is intervention…the user says what they would do and then the UX designer shows them the next result. This can be done with paper prototypes. Finally, you have functional interactivity, where the various UI components actually work.
Low fidelity advantages: Quick, easier, and cheaper to create and modify. More importantly, people are more willing to give feedback on something that looks finished. People are afraid to give feedback on something that looks polished because they don’t want to hurt your feelings, but if you provide a low-fidelity wireframe, you will get much more candid feedback.
Low fidelity disadvantages: You might get detailed feedback on irrelevant details (“this button should be square and not rectangular”). Limited ability to watch users interact. Some users cannot visualize the final product from a low-fidelity version.
High fidelity advantages: The prototype is more realistic. Easier to understand and less room for misinterpretations. You can watch the users interact with the design.
Low fidelity disadvantages: More expensive to create, less encouraging of feedback, people focus on minutiae, easy for designers to become emotionally involved.
(“You might throw in lorem ipsum text and then have people correct your Latin.”)
As you move farther into development, fidelity generally needs to increase.
Higher fidelity is important when you have higher usability risks due to lots of interactivity, complex UI, new interactions and content (for dev team or users), where in user task flow does UI occur (earlier is riskier).
Tools & their best uses
Bar napkins: Good for early conceptual designs, not so good for felt tip pens and putting a wet beer glass on.
Paper prototypes: Can create the various interfaces and do some paper-based flow testing. Not so good for a sense of scale or for assessing content.
PowerPoint: Can do hyperlinks and action buttons. Create each interface on a slide and then link them with PP features. Use slide sorter and rearrange to simulate various user workflows. For web design, put a browser window on the slide master to force you to stay in the browser space. Good for sense of physical navigation, planning layout, producing paper output, presenting look and feel for interactive web pages. Not so good for complex interactions and for look and feel of applications.
Visio: Pretty good set of widgets for making realistic-looking dialog boxes. Similar pluses and minuses as PowerPoint, but also good for look and feel of applications. Can use to incorporate wireframes with flowcharts, use case diagrams, and other macro-design tools.
Balsamiq Mockup: Presenter’s favorite tool (mine, too). Extended demo. If you’re interested, try it online for free. Realistic enough to help designer imagine what the user experience will be.
Pencil (Firefox plug-in): “they have the world’s worst online help”
Axure demo: Can build tooltips. Higher fidelity than Balsamiq. Lets you take note and annotate the fields and then print as a Word file. Use to lay out business rules, alternate text, and more. Suitable for Web 2.0 interactions, which are difficult or impossible in Visio.
Cardinal sin of blog (and technical) writing: making the reader feel stupid
Want to get me riled up? You can easily achieve that by making me feel stupid while reading your blog.
I read a lot of blogs about technology, and I’ll admit that I’m on the periphery of some of these blogs’ intended audiences. That being said, there is no excuse for starting a blog entry like this:
Everyone’s heard of Gordon Moore’s famous Law, but not everyone has noticed how what he said has gradually morphed into a marketing message so misleading I’m surprised Intel doesn’t require people to play the company jingle just for mentioning it.
Well, I must not be part of the “everyone” collective because I had to think long and hard about “Gordon Moore’s famous law,” and I drew a blank. (Here’s a link for those like me who can’t remember or don’t know what Moore’s Law is.)
Making a broad generalization such as “everyone knows x” is always dangerous. This is true in blog writing as well as in technical writing. In our style guide, we have a rule that writers should “not use simple or simply to describe a feature or step.” By labeling something as simple, it’s guaranteed you will offend someone who doesn’t understand the concept. For example, while editing one of our white papers about the DITA Open Toolkit, I saw the word “simply” and took great delight in striking through it. From where I stand, there is little that is “simple” about the toolkit, particularly when you’re talking about configuring output.
Don’t get me wrong: I’m not saying that a blog entry, white paper, or user manual about very technical subjects has to explain every little thing. You need to address the audience at the correct level, which can be a delicate balancing act with highly technical content: overexplaining can also offend the reader. For example, in a user manual, it’s probably wise to explain up front the prerequisite knowledge. Also consider offering resources where the reader can get that knowledge: that way, you get around explaining concepts but still offer assistance to readers who need it.
In the case of online content and blog entries, you can link to definitions of terms and concepts: readers who need help can click the links to get a quick refresher course on the information, and those who don’t can keep on reading. The author of the blog post in question could have inserted a link to Moore’s Law. Granted, he does define the law in the second paragraph, but he lost me with the “everyone has heard” bit at the start.
That “everyone has heard” assumption brings me back to my primary point: don’t make your readers feel stupid, particularly by making sweeping assumptions about what “everyone” knows or by labeling something as “simple.” Insulted readers move on—and may never come back.
Webcast: DITA-FMx demonstration
This webcast demonstrates using the DITA-FMx plugin with FrameMaker 9 to author, edit, and create output from DITA content. Topics covered during the demo include creating DITA topics using different options and templates and generating a book from the map and then saving to a PDF file.
