This is the Foreword to the second edition of Developing User Assistance for Mobile Apps.


It’s somewhat surprising how ubiquitous smartphones are among tech writers (almost everyone has one), but how infrequently tech writers engage in user assistance for these same mobile devices. Why aren’t technical writers saturating the exploding mobile market by playing key roles with documentation on mobile development teams?

One reason might be a question of scope and complexity. Companies who hire professional technical writers tend to have significantly complex content to document, requiring the full-time attention of technical writers to gather, create, and publish the information. Mobile apps, on the other hand, tend to be much simpler and easier for users to understand. There’s only so much you can do tapping a small screen with your thumbs. The amount of help content is also substantially smaller and briefer.

But there’s probably another reason why we don’t see more technical writers in the mobile space: tech writers tend to stick with information development, creating content in their own spheres and handing it off to dev teams to link to.

More than anything, Joe’s book will suggest that for tech writers to thrive in the mobile space, their roles must go beyond documentation. The technical writer in the mobile space plays a UX role, integrating help content at key points of interaction in the user interface. Joe argues that the best help is not a separate page that opens up outside of an app, but rather appears in the UI at the moment the user needs it.

Only when tech writers start tearing down the artificial barriers between the help system and the application will they begin to create successful user experiences in mobile. Joe shows a wide variety of approaches for integrating help in mobile interfaces, grouping the approaches in different patterns and getting into the nitty gritty details of actual apps. He doesn’t wander in theoretical abstractions. Instead, you’re immersed in a visual panoply of app screenshots showing a wide variety of help interactions. He builds his analysis from his immersion in apps and gives you details only an experienced professional, aware of all the nuances and intentions and effects of help techniques, can provide.

Beyond showing patterns of help integrated in mobile interfaces, Joe also provides a wealth of technical detail that will be immediately helpful to anyone getting his or her hands on code. Whether you’re working with iOS, Android, or Windows Phone, he gives you step-by-step details for setting up emulators, working with web views, installing SDKs, configuring development environments, and more.
Giving so many technical details may seem a bit risky given the constantly changing nature of the domain, but those details might also be the most immediately helpful as you ramp up technically to move beyond just being the doc person to being an actual team member involved in UI development.

Without a doubt, Joe’s book is the definitive work on user assistance for mobile. But as he points out, it’s not just about mobile. Although the examples are grounded in the mobile space, it’s not a stretch to envision similar techniques for desktop help, or to consider how desktop applications will evolve into the mobile space in more seamless ways — taking their help with them.

— Tom Johnson is a technical writer in San Jose, California, mostly writing developer documentation, including documentation for APIs. He publishes the popular blog I’d Rather Be Writing