How to Search Engine Optimize (SEO) Your Help Documentation

Search engine optimization 1.0 → How to Search Engine Optimize (SEO) Your Help Documentation 1.1 Introduction, frames, iframes, and tech comm tools (search engine optimization) 1.2 Single sourcing and duplicate content (search engine optimization) ...

Narrative Workflow Topics: Helping Users Connect the Dots Among Topics

I'm continuing my series of posts addressing why users can't find information in help and what to do about it. The following reason received a high number of votes: The answer is an isolated task, but the user needs a more connected beginning-to-end workflow. This answer has received 66 votes. So far, the highest number of votes any response received is 78. (By the way, if you haven't taken the survey, you can still do so here at the in...

Reader Question: How do I create online help, how to guides, quick start tutorials, or video tutorials?

A reader asks, I find your advice extremely helpful, thanks! Where can I get instruction to learn how to do 10-A tech writing deliverables, Is there a guide or open course university to show you how to write online help, how to guides, quick start tutorials or video tutorials? Thanks, It's not often that someone asks for advice for such all-encompassing instruction in tech comm, so I thought I'd take a stab at actually answering it. Exa...

Recommended Article: APIs are delivering on their promise (SD Times: Software Development News)

Software Development Times has an interesting article on about APIs: If you believe a recent report from analysis firm Gartner, in just two years, we'll be overrun by citizen developers (normal, untrained computer users) building 25% of new business applications. A major facilitator for these newbies? Some have posited that cloud-based API mash-ups would be so easy to use, toddlers would soon be selling mobile apps. But now, San Francisc...

Creating Good Content Requires Cross-Department Collaboration

One traditional stereotype about technical writers is that they work long hours in isolation, almost like a hermit in a lone cell immersed in deeply technical material, trying to make sense of it all by themselves. We know that stereotype is a recipe for failure. Collaborating and sharing information across departments is essential for creating the right content. But exactly how we are to collaborate across departments isn't as well defin...

Sticking with Obvious Information Versus Creating Information that Users Need

In my recent tech comm poll about why users can't find information in help, one of the top answers was the following: The answer isn't in the help because the help sticks only with obvious information. No doubt at some point in your life, you've clicked a help file and browsed around only to find that the information is too basic and simple to answer any real troubleshooting questions you have have. Through repeated experiences like thi...

Subheadings: Perhaps the Most Useful Technique in Technical Writing

My recent poll on why users can't find answers in help material surfaced an interesting paradox. Consider these two reasons: The answer is buried in a long page, but the user only spends 2 minutes max on a page scanning. The help has been fragmented and dispersed over many small topics so the help is a maze. In other words, help is either too long so users can't find the answer, or help is too short so users can't find the answer....

Examples Are a Primary Way That Complicated Concepts Become Clear

In my recent poll about why users can't find the answer to help, one of the top answers (so far) is the lack of examples: The help doesn't provide concrete examples that make the concepts understandable. (View total votes.) I've long been a fan of examples in help documentation, but I didn't suspect they played such a large role. In fact, one rarely hears any presentations or reads blog posts on using examples. It's time to give this t...

Interactive Poll: Why Can't Users Find Answers to Their Questions in Help?

I'm preparing for an upcoming presentation at a local STC chapter in the SF Bay area. I'm hoping to get some feedback before I finalize this presentation, so if you have some ideas, I'd love to hear from you. Here's my draft: Why Users Can't Find Answers to Their Questions in Help Content One of the main goals of help material is to help users find answers to their questions, but so often this doesn't happen. Users foray into the help ...

Why I Test Nearly Everything

One of the forms of writing I like most is the essay, which is a form that has strong origins with 16th-century Michel de Montaigne. Montaigne saw essays as a kind of attempt or test of an idea and his judgement about it (see Montaigne's Moment). Since I like the essay format, it's not surprising that I also like to test content. In fact, testing content constitutes one of the main characteristics of good technical writing. By testing con...

When Organizing Big Data Content, It's Okay To Be Messy

I recently listened to an O'Reilly programming videocast interview with Travis Lowerdermilk about his new book, User-Centered Design: A Developer's Guide to Building User-Friendly Applications. During the videocast, Travis notes that according to Jakob Nielsen, you need only 5 users to identify most of the problems with a UI design. Lowdermilk acknowledges that the idea has been challenged by some, including Jared Spool and others (see Wh...

7 Ways to Learn Difficult Subjects in Order to Write Useful Content

Since I switched jobs about 6 months ago, I decided that I wanted to move toward writing developer documentation. Not only is the job market for this skill extremely hot, it's also a challenging and interesting landscape to explore. I'm currently writing a lot of code samples for a JavaScript SDK. Even though I'm comfortable with CSS, HTML, and a lot of technical topics, like designing and developing WordPress sites, I've had to ramp up o...

Turning Around the Disdain for Help by Focusing on Content

For a long time I pursued findability as a solution to fixing the documentation problem. But lately I've been less persuaded that findability will solve documentation's ills. Instead, I'm become convinced that what's really wrong with help is the content itself, not necessarily allowing people to find it. Why? Because "it" often doesn't exist. The user is trying to find something that hasn't been created. What's really wrong First, a quic...

Messages from Sponsors -- July 2013

Etteplan | Tedopres Etteplan | Tedopres releases HyperSTE 5.0 with support for ASDSTE100 Issue 6 and new authoring applications HyperSTE 5.0 is a major update introducing support for new authoring applications, including Madcap Flare and Oxygen. In addition, HyperSTE now fully supports Issue 6 of the ASD-STE100 specification. What is new in HyperSTE 5.0: Full integration of the ASD-STE100 Issue 6 specification. Now also compatible with: ...

Sample Chapter from Word Up! How to Write Powerful Sentences and Paragraphs, by Marcia Riefer Johnston

Marcia Riefer Johnston recently published Word Up! How to Write Powerful Sentences and Paragraphs (And Everything You Build from Them). I had a chance to read an early draft and provide feedback. I really enjoyed the book, so much that I agreed to appear in a promo video: I gave a short quote in the "Advance Praise" section of the book, noting that Word Up is "Light, fun, and enjoyable to read. Marcia approaches grammar and style with a...