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...
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...
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: ...
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...
Since I wrote my post about how help needs to be more engaging/appealing to users, I've been mulling over a better approach to help. I'm convinced that one key to creating good help is producing the right information. In my last post, I wrote about the need to answer the user's question as the foundation for creating good help. But then I was reading something Mark Baker wrote about addressing purpose instead of answering questions, and I...
A few weeks ago, I added some social network functionality (Buddypress) to my site as well as a Question and Answer module. You can read about the features here. Unfortunately, the social network plugin added about 5 seconds of load time to my site, and despite my attempts to speed it up, Buddypress is just slow. Caching plugins seem to pose problems with Buddypress, too. The Q&A plugin required user registration to work well (registr...
In my last post, I reflected on the most successful experiences I've had in connecting with users and decided that a foundational principle for successful user help is to answer the user's question. I also realized that if there's been a transformation in the user experience of help at all in the past 50 years, one that has had a positive impact on the user experience, it's this: you can type a question into Google and find an answer. The...
In an earlier post (Do We Need a New Approach to Help?), I surfaced concerns about the approach to help material in general and asserted that despite 50 years of innovation, most users still have the same reaction towards help: they dislike it and find it a chore. Lots of commenters agreed that we need to create more engaging user experiences. Laura Palmer added that converging instructional design with information design can be a useful ...
Larry Kunz's recent webinar, The Future of Technical Communication, is one of the best webinars I've listened to recently. Larry's message is not only on target and insightful, he also articulates concepts in a clear, organized way. It's easy to listen to and you'll get a ton of useful information out of it. Larry mentioned several trends in tech comm and then several skills tech writers can develop to meet those trends. The following are...
Listen here: Download MP3 (right-click, then Save Link As) PowerPoint Slides PDF version This is an audio recording of a presentation I gave at UA Europe in June 2013. Here's the description: Next to Google, YouTube is the second most popular search engine on the web. The popularity of video, especially for how-to scenarios, suggests that it should play a more prominent role in user assistance. However, creating vide...
Listen here: Download MP3 (right-click, then Save Link As.) PowerPoint slides PDF version of slides This is an audio recording of a presentation I gave at UA Europe in June 2013. Here's the description: Users tend to search Help material when they have a specific question they're looking to answer. In contrast, users tend to browse Help material when they don't know exactly what they're looking for. Browsing often lea...
I've spent the last few days at UA Europe in Manchester, England, where I was invited to speak. I'll shortly post recordings of my presentations -- one on findability, and one on video tutorials. Both are important topics. But there's an even more important topic I haven't addressed much: the content of help itself. Conferences usually prompt reflection of some kind, especially international conferences, where attendees are much more dive...
The singularity refers to a point in time at which technology will transform society in such far-reaching ways that it will be impossible to conceive of what life was like before the transformation. Or something like that. I actually think reflect about the directions technology is taking us now and then. When you live in Silicon Valley, where practically every company is a tech company, it kind of makes you think about the future. I rece...
June 26 update: I've had some issues with site speed after implementing Buddypress. Hold on while I figure out the best approach here. Things may be in flux a while. Most of the interesting things happening on the web seem to involve a strong community element. Think about Wikipedia, Wordpress, Twitter, Youtube, Quora -- all of these sites thrive on community content and interaction. So this weekend I decided to update a few features on I...
It's always fun / makes my stomach turn to wake up to a newsletter that starts out saying, "Tom Johnson's post Structured Authoring Versus the Web triggered a wave of responses across the tech comm community." I've been thinking about that post and discussion (1, 2 , 3). A lot of people have made excellent arguments in response and called me out on being short-sighted. One person noted that I should nuance my opinions with more notes and ...
