Joe Welinske is the president of WritersUA. Joe has been involved with software documentation development since 1984. His focus is producing high quality seminars and conferences for the user assistance community. Contact Joe: joewe *at* writersua *dot* com
I had a chance to take a good look at Doc-To-Help 2012 this past week. Since I was in Pittsburgh to speak to the local STC chapter, it worked out to stop by the offices of ComponentOne. Dan Beall, Nicky Bleiel and Brad Keller took me through some of the new elements.
Released in late January, Doc-To-help 2012 has some important new features. Maybe the most prominent is that of Mobile Help. Mobile devices have become a popular method for accessing documentation as well as running applications. Doc-To-Help is poised to support this through a new output target. Now, Doc-To-Help users can add mobile to the single-source options that already include HTML Help, PDF, Net Help, and others.
Mobile Help is a web-based version of the documentation that is encapsulated in a navigational wrapper. The wrapper includes controls for search, a table of contents, and an index. The table of contents uses an iPhone-style method of layering multiple levels of the topic hierarchy into a series of horizontal flicks. Other common Help features that are supported include previous/next, popups, and expanding text. If you are linking to mobile topics from an app, you have the option of displaying the associated topics without the navigational wrapper.
A major feature of Doc-To-Help has always been its use of conditional text for single-sourcing content. This continues to be important with mobile. The language for touch interfaces is different from that of the desktop. Also, limited screen real estate makes it wise to streamline content for display on smaller mobile devices. Using a combination of build expressions and conditional variables, it is possible to highly customize your topics.
Another new feature in Doc-To-Help 2012 is support for Hebrew and Arabic presentation. D2H can automatically adjust your documentation to right-justified, right to left reading. This can be enabled by selecting pre-set Hebrew and Arabic themes, or by selecting that setting in a custom theme.
Doc-To-Help 2012 also includes support for Office 365. But I didn't have enough time to check that out.
I received my Kindle Fire last week. It is a nice device and Iím having fun playing with it. It was also nice to get a welcome email from Kindle to coincide with the arrival of the Fire. The message included a Getting Started section with links to relevant pages on the Amazon support site.
More and more organizations appear to be finding value in making an active effort to let customers know about web-based user assistance offerings. Not only does this contribute to a higher level of customer satisfaction, it can also reduce the likelihood of customers resorting to phone support.
Of course, this assumes you have your UA content on a public-facing server. It is the embedded links in the email that make it an easy immediately rewarding decision for your customer to click. If they need to leave the email message and navigate to a topic, it is much less likely the message will have an impact. An added benefit of your customers clicking from an email message is that this adds traffic to your Help site and elevates those topics in search engine results.
One of the keys to success with UA emailings is to decide on a very small set of topics to present. Three or four are probably the max. A welcome message is not the place to for a comprehensive list of Help topics. Generally, the most useful information will be related to installation and setup. Ideally, those topics will then have links to guide the customer to additional topics and layered detail.
Another key is to clearly separate the user assistance content from any marketing and upgrade information. In many organizations, the sales arm controls customer contact. It may take some persuading on your part to help the sales department understand the usefulness of a UA-specific email push.
While these tips seem to be based on working with traditional desktop applications, they have relevance in supporting mobile apps as well. Connie's first two items - staying in the loop and access to development environments - are both key in working with mobile apps.
To some extent, staying in the loop may be more important in the mobile arena than with desktop apps. Mobile apps tend to have a relatively fast design cycle and it is important to part of the early meetings. User interface elements get labels very quickly and you want to be able to have input from the start. Ideally you will also have time to conduct usability tests on the user interface text choices. Using the most precise and communicative words and phrases is a contributing element to a great user experience with small screen devices.
Being able to experiment with mobile UI text is made much easier with access to the development process. The simulators/emulators provided in the various mobile development environments provide an excellent way to perform usability testing. It is important to maintain access to mobile builds and be familiar with tools like Interface Builder in iOS.
The Techwhirl article also lists creating a documentation plan and setting a date for documentation freeze.
The rapid, interative development in mobile app development can play havoc with a very detailed doc plan. It helps to follow Agile principles, or at least be nimble in responding to changes. Initial user feedback after a first release can, and often does, engender significant changes in the UI.
With respect to deadlines for documentation, Help information that is embedded in native code can often be added or fine-tuned in those frequent releases. Users have become accustomed to regular updates through the iTunes store as well as OTA (over the air). We have the flexibility to update our docs at many points in the lifecycle of the app. This is even more true if the Help is served on-demand through a wifi or cell connection.
Iíve been really interested in following the developments about Microsoftís Windows 8 operating system. The keynote presentations at last monthís Build Conference painted a picture for a very innovative and exciting future for Windows. The heart of it is the ďmetro-styleĒ interface that is tailored toward touch screens and tablets.
I installed the Win 8 Developers Preview right after the conference. It was a surprisingly easy installation. In fact, it actually resuscitated an old laptop that I had more or less junked. The new OS worked fine on a machine where Win 7 had struggled with the older processor and slower drive.
Last night I attended the monthly meeting of the .NET Developers Association. This is a Seattle-area user group that features speakers and presentations related to Windows application development. The speaker, Doug Seven, is a VP at Telerik which provides end-to-end application development across all the Microsoft platforms. Doug used to be the Director of Product Management for Visual Studio and the .NET Framework at Microsoft. So he was in a great position to give a balanced view of whatís going on under the hood of Windows 8.
The first thing Doug provided was a chart identifying the framework of Windows 8. According to Doug, this is a more accurate version than what Microsoft presented at the Build Conference.
Windows 8 is basically made up of all the stuff currently used to build Windows 7 applications plus the new bits that support the metro-style apps. Both the Windows 7 and metro-style parts live on top of the Windows kernel.
The Windows 7 OS is intact within Win 8. It continues to support the same application environment, libraries, languages, tools, etc. In the figure above, the Windows 7 section is in blue. The Windows 7 applications reside in what is being referred to as the ďdesktopĒ mode Ė the current public face of Windows.
The Win 8 metro-style apps are developed using familiar technologies but in a completely new and somewhat segregated development environment. All of these apps are built on a new API called WinRT. Unlike desktop apps, WinRT apps are encapsulated with boundaries that limit their interaction with certain areas of the operating system.
Doug noted in his presentation that while familiar languages are used with WinRT, the code is not necessarily portable from desktop apps. There are some significant differences in how desktop and metro-style apps are put together. For example, the .NET framework for metro apps is just a subset of what can be done with .NET for the desktop.
In that same vein, although the metro-style UI looks similar to Windows Phone apps, there is currently not much commonality under the hood. The term metro-style itself is an unwieldy attempt to distance the name of the Win 8 apps from the ďmetroĒ label used with Windows Phone apps.
A new version of Visual Studio has been created to support Win 8 development: Visual Studio Express for Windows Developer Preview. This version of VS contains sample projects, templates, and code libraries to give early adopters something to work with. You can create projects with any of the three presentation layer combinations described earlier. VS includes a simulator which provides a virtual Windows 8 environment for testing your apps.
One element in metro-style development that is similar to Windows Phone development is the use of manifest and common publishing elements to package the apps for distribution.
There are a couple of interesting items related to support for cascading style sheets. One is the Win8 support for vendor-specific implementations. That means that you are able to do things with CSS that wonít work outside of Win8. Also, you can use CSS to specify how the UI of your app will change if a user changes the broad ďthemesí that control the overall look and feel of the apps.
My new book, Developing User Assistance for Mobile Apps, was published a couple of weeks ago on Lulu. It was an interesting project. The writing took just under two months to complete. The majority of the ideas for the book came out of the work I had done for clients over the past couple of years. I have two main objectives. One was to show that user assistance has an important role in mobile. The apps that you see in the top ten lists in iTunes do not at all represent all the apps being developed by corporations as new arms of existing enterprise software systems. The other objective was to expose readers to the intricasies of providing UA that is compatible with native apps. Relying on ePUB and external Help files is a poor substitute for UA integrated directly in an app.
The images and links from the book are freely available.
The Design Library on the Blink Interactive web site offers some useful tips for user assistance developers. The Case of the Empty Queries is a fix that is easy to implement. If you use any type of entry fields you should check to see if it supports some form of "hint" attribute. The Video Help Content technique looks like a good way to layer support content without obscuring the main workspace. Language Counts is a good reminder that poor UI text choices can significantly impact the user experience.
Microsoft released a developer version of the new Windows Phone OS last week. As a registered developer I was able to install the "Mango" on my Windows Phone. After a big launch last October there hasn't been to much to talk about for Windows Phone. While the developer NDS precludes and discussion of the features, there are good posts Mango on Engadget and other sites.
The most important thing about the release is that it represents a strong desire on Microsoft's part to keep rallying the development corp to build new apps. The consumer release won't happen until the end of the year. But the platform really needs more quality applications. Most of the apps in the Marketplace are trivial and uninspiring. There also needs to be a bigger committment from corporations to create apps for Windows Phone in addition to iPhone and Android.
The Dashcode documentation describes it best:
The Browser template creates a web application that supports navigation through multiple levels of content. A web application developed with the Browser template is well-suited to displaying hierarchical information through which users can drill down.
The default web application provided by the Browser template contains a list view for the top level of the content and a detail view for the second level of the content. Selecting an item in the top-level list automatically reveals the detail view associated with that item. You can add additional list levels and you can add content to the detail views.
Dashcode provides a nice WYIWYG environment for developing your content. It also can launch the content in the iPhone simulator.
It is important to realize that the Dashcode output is all open standard code and can be interpreted by browsers on any platform. If you donít mind authoring on the Mac, Dashcode can be a cheap and easy tool for developing mobile Help files. The output of the Browser template even looks like the solutions weíve seen emerging from authoring tool vendors.
Xcode is available through the Mac app store for $4.95. It is not available for Windows.
Iíve made a point of sounding the alarm in the technical communication community that we need to keep up with what is going on with mobile devices and applications. But it is easier said than done. Iíve been focusing on the mobile space for the past two years and I still find it difficult to stay up-to-date on the ever-growing list of devices and associated operating systems. Iím actively working with iOS, Android, and Windows Phone 7 and it is a struggle to deal with the on-going changes in just those three ecosystems.
One of the things that keeps me going in this techo-chase is that I find a lot value in it. There are distinct differences on the surface of these environments and also under the hood. Windows Phone has a completely different form factor from iOS. And Android is different from both of those. A person who buys an iPhone over a Droid is doing it for reasons beyond the cost of the device and the service contract. I donít think you can effectively develop user assistance for a mobile app without understanding the nuances of the user interface and the expectations of the customer. It has been very useful in identifying ideas for better ways to provide user assistance.
One of the challenges in keeping up with the device explosion is the cost of the devices. It isnít practical to have access to all possible devices. It may be difficult even to justify having three or four of them. The average cost for a smartphone is in the neighborhood of $500-600. In the United States this cost is often subsidized by the communication networks in exchange for taking on a 2-yr. service contract. Those contracts can easily cost $2,000-$3,000. Add to that the obnoxious practice whereby the networks hold back on software updates in order to boost the sales of new devices and extended contracts.
For me personally, I only need one contract - for my primary phone - which happens to be an iPhone. But I also have an Android G1 and an HTC Surround for Windows Phone. It isnít practical to have multiple contracts. And I also canít afford the retail price for new phones. What is a UA professional to do?
The iOS is not a problem. Apple pushes everyone forward at the same time on devices and software. If you like Apple products you can figure on needing to upgrade equipment every two years. The rigid control Apple has over their platform means you donít have to deal with more than a couple variants in technology at any one time. I will probably keep this as my primary personal device because of that.
Android is another story. You can see the quick evolution of the platform from the ever-increasing set of statues outside the Googleplex in Mountain View, CA. In the past three years there have been six major updates with sweet names Ė from Cupcake to Honeycomb. The device I have is the G1. This is the original Google phone that came out in 2008. It shipped with the first public release of Android which was labeled 1.5 and called Cupcake. There was another update for 1.6 (Donut). However, my carrier TMobile stopped shipping updates for Android after 1.6. My G1 is long out of its service contract but it still works fine. In order to keep up with the software I had to root the phone and find open-source builds. That same G1 is now happily running Android 2.2 (FroYo). Iíll write a future post about updating mobile software because I think it is going to be something that we do more and more as technologists.
My interest in working with Windows Phone introduced me to another problem in keeping up-to-date Ė that of affording new technology. One way to cope is by buy unlocked phones that are out of contract. The fast growth of the smartphone market means there is a burgeoning market for used phones. I bought a like-new Windows Phone 7 HTC Surround on eBay. It was about half of what it would have cost to buy the device new without a service contract. Buying an unlocked phone meant that I didnít have to deal with the rooting process I went through with the G1. The Surround displays the Windows Phone OS just fine. I use the wi-fi capability for Internet-based activities. I can link the phone to my laptop which is running Visual Studio for Windows Phone 7. I also bought an AT&T pre-paid SIM card for $25. That gives me the ability to test apps via 3G networks on a pay-as-you-go basis.
Time to breath now that our WritersUA Conference is in the rearview mirror. And we looked in the mirror for our opening conference sessions. We posted a number of multiple-choice questions to the audience. Everyone had an individual response device so we could get an immediate tally of responses. You can download the summary pdf. You can also download my podcast summary of the results.
A colleague, John Daigle, recently asked me if I still had a version 1 disk of RoboHelp. I found it sitting in a box of old floppies that includes the first three versions of Windows. I can't remember the circumstances of getting it. I think I did my first RoboHelp projects for a client in 1991. The disk says 1991-1992 so it must have been 1992 when I got my own copy. I know there weren't a hundred thousand copies in circulation so mine was probably 1,246
At that time Blue Sky Software was the owner of RoboHelp. They had a tiny office just off the beach in La Jolla. The palm tree on the disk label actually made sense. The first time I visited their office we had to move furniture around to get enough space for several of us to have a conversation. A sliding door led right out onto a sunny deck. Twenty years later the product couldn't be any more different than the first version. And Adobe couldn't be a more different owner. The product purpose is the same tho; converting the words and images of documentation into a digital equivalent.
As a technical communicator with twenty-eight years of experience I never realized that content strategy was ever "just the preserve of the web professional." I'm not sure what exactly I was doing with my word processor in the dozen or so years before the Internet became mainstream.
I think the post is more useful in illuminating the failure of technical communicators to make their contributions visible. As a community we tend to do a poor job of tooting our own horn. The author of the article, Jeremy Baldwin, mentions content marketing as a key aspect of a content ecosystem. I would agree with that. It is important to make sure that our efforts are recognized by both our customers and our employers.
Often we complete a documentation project and it just gets dumped into a knowledge repository. Very few organizations take the time to make sure customers are aware of the new and updated content. There are certainly numerous mechanisms to do that. RSS feeds, Twitter, and emailings are natural and relatively inexpensive customer touchpoints.
Documentation departments should become accustomed to reaching out to customers whenever fresh content is generated. This also serves as a very public broadcast within our organizations as to the value we are contributing to the enterprise.
I think the important word in this article is ďdiversifyĒ. The shift in focus represents attention to the potential for apps sales in the growing Android market and the emerging Windows Phone 7 market. The iPhone app market has enjoyed heavy development over the past three years and it makes sense that organizations would want to explore other platforms.
The evolution of the iTunes store for apps also showed how an early presence can have a lasting effect. It was much easier for a good product to find its way to the ďmost popularĒ lists in 2008/09. Now with 250,000+ apps in the store it is much harder to be visible.
This is a continuation of my previous post on creating instructional videos.
The central element of most video editing tools is the timeline. If you havenít worked with video editing before it will probably take some time to understand how to integrate your various media along the timeline. All of your video clips, narration, music, captions, and special effects will be attached to time segments along a chronological line going from left to right in the editing tool.
In most editing tools, the various media elements are added to the timeline in separate rows. Often you can drag and drop icons representing your media directly into a row of the timeline. Media elements can be dragged forward and backward in the timeline or locked to very specific points. Media elements located at the same point along the time line will be synced together in the movie.
There will be a window in the editor for viewing media clips individually or combined with other elements. This makes it easy to quickly review and modify the clips.
Any decent editing tool will make it easy to trim video and audio clips into a scene. In and Out buttons determine what makes up a scene. The names of these buttons may change but they work the same. You start playing the clip and decide where the scene should start. Pause the clip and click the In button. Then play the clip until you find the end of the scene. Click the Out button. Usually the In and Out points can be adjusted with slider controls. The original clip is still intact. But only the selected scene will be included in your published video.
Most demonstration videos are created with a single video/audio track. The person demonstrating something will be talking about it at the same time. This saves time if you can do it in one take without mistakes. But often it works out better to have separate audio and video tracks. What I usually do is capture the video. Then while watching the recorded video I record the narration. For live video it actually works better to cut the action to the narration.
Static images like screen captures, photos, and titles can be dropped into the timeline as well. You set a duration for the amount time you want the image to appear on the screen.
Transitions are added into the timeline as objects. Usually there is a gallery of transition types to pick from. Transitions get assigned a duration like static images depending on how fast you want to exit from one scene and transition into another scene.
Music can be an entertaining enhancement at the beginning and end of a video. Good tools will let you set the audio level of your music and gradually fade it in and out. Music files are dropped into the timeline on a separate row from the narration. Mixing tools let you set the individual volume levels for narration and music.
All good editing tools will let you do all of the above. Where the tools will vary is in the level of sophistication and control that is provided.
The TWiT network is a great place to get information. The acronym is for the original show name This Week in Tech. The roster of shows has increased dramatically over the past couple of years. The programs I listen to are This Week in Tech, This Week in Google, Macbreak Weekly, Tech News Today, and Windows Weekly. They have a revolving door of regular contributors as well as special guests. The content is definitely oriented toward mainstream consumers of software and hardware products. They rarely get into enterprise stuff. However, I find it a good way to keep up with the current buzz about technology.
The TWiT web site has an archive of past programs, links to show notes, as well as many other useful elements.
I mostly listen to the audio podcasts through iTunes. But most of the shows also have video streams.
They have a regular broadcast schedule and you can watch or listen live. There are free streaming apps for the iPhone and iPad. When I want to watch the video, I usually do it through my Roku TV box where TWiT has its own channel.
I was really shocked to hear that Anne Bradbeer died. She was a regular participant at our conferences. Anne was always a lot of fun to hang out with and she was always involved in interesting projects.
What I heard from others was that she'd had liver disease. She fell into a coma and passed away. I donít have any other details.
One of the more interesting trends in UA is the use of a customer email broadcast to provide Getting Started tips. After a person buys a product or subscribes to a service the vendor sends out an HMTL email message with Getting Started tips. When these kinds of messages are done thoughtfully I think they can be extremely valuable.
Apple does a really good job with this. I made online mail orders for both the iPad and iPhone 4. Before I received either product I received a Welcome note by email. The mail message was not cluttered with any sales garbage. It was pure user assistance.
The iPhone message told me where to find the User Guide on the device and provided links to videos about four topics. Each of the topics was useful in learning about the new phone. Quick scrolling, saving images from the web to the device, selecting wallpaper, and creating a playlist. The email also offered a free phone conversation with a tech support person to explain the new Facetime feature.
After subscribing to the Pandora music streaming service I received a message with a useful tip that described how to ďseedĒ songs or artists to have more variety in a play list. Other tips pointed to a support blog and supplementary resources about artists.
Each of the tips was less than thirty words. The point of user assistance mail is to help the user begin working with your software with a positive experience. You donít want to drive your new customer into a bottomless pit of arcane documentation.
The cost and ease of implementing a campaign like this will vary from organization to organization. There is generally a small financial cost to emailings. The construction of the email could be done in a day. The most critical part would be designing the message to be action-oriented and really helpful. However there can be expensive customer satisfaction costs if the emails are filled with notes about upgrades and add-ins. These emails should not be connected to sales and marketing campaigns.
The cost is $135. The event takes place at the Bellevue North Campus on consecutive Monday evenings, October 11 and 18 from 6pm-9pm. Registration is open. This class is not available online. It won't be taught again until Fall of 2011.
Linkedin added in a security verification system and it really ticks me off. Iím an active user and manage the Software User Assistance group so I am always logging in and out. Now I have to do the extra step of typing a captcha. And captcha sucks too. I canít read half of the letters. And they donít like to use real words. A total pain. I never noticed any spam when using Linkedin before this.
I sent a complaint by email but only received the ďThank you blah blah. Have you tried to find the answer in our blah blah.ď Very unhelpful. I have to think that providing a generic answer to someoneís email is worse than just ignoring it. I never have a high expectation for an email reply so when it happens positively Iím impressed. When it is just crap then it reduces my satisfaction with the product or service.
I stumbled on a feature in the Date/Time settings of Windows that I never saw before. If it was there before Windows 7, I donít see how I missed it. First you identify the zones for which you want to monitor the time. Then when you put the mouse pointer over the local time indicator in the try you get a popup with that shows all the different times. This is the kind of useful stuff that needs to come in a tip by email after you install software. Or as a support tweet.
Creating You-Tube-style videos for instructional demos - Sept. 16, 2010
Iíve been doing a lot of work with instructional video over the past few months. The activity has been for clients with iPad and iPhone apps. The purpose is to provide an up-tempo visual aid for topics that are pain points for users.
It has been fun working in the video medium again. I had been involved with video instruction over twenty years ago. Using interactive laser disc. Those lp-size glass platters are probably unrecognizable to anyone under 30. Laser disks only found a niche for displaying high-resolution movies in the home and for computer-based training. For CBT, the video was burned to the disk in write-once mode and at a fairly high price. A PC needed to be outfitted with a special hardware controller to search the laser disk. The PC was also the host for any graphics, audio, or branching logic. What you ended up with was a big pile of expensive gear that the learner needed to come to for the instruction.
Obviously the technology is much more accessible now. Videos are stored digitally on whatever is the most convenient device. Local storage is easy and cheap. And more and more video is streamed from remote servers. Music and narration is encoded with the video stream. Browser standards and codecs have made the display of a video universally easy and ubiquitous.
The price points for editing tools have changed for the better. You can purchase perfectly capable editing tools for $75-$150. For You Tube-style instructional videos there really is no need to spend more. Editors havenít changed in functionality much though. An editing tool lets you input clips, it has trimming tools for setting in and out points on clips, transitions are added between clips. Parallel tracks along a timeline allow for music, narration, captions, and special effects.
In a future post Iíll go over some of the challenges getting started with your video production.
Discontinuation of Google Wave - Aug. 8, 2010
Google made a surprise announcement this week by eliminating development for their Wave technology. Surprising because the technology hasn't been out for too long. The first announcement was in May of 2009. There was an initial period where Wave was only available to a limited number of users. The full public release was just last May. I suspect that the technology didn't have enough users to make it worth the on-going internal development resources.
I was intrigued by Wave when it was first announced last year. But I never used it beyond experimentation. The capabilities seemed to be robust but there was no clear use case. The set-up was also a bit squirrely. Adam Lasnik of Google gave a really comprehensive introduction to Wave at the Seattle Conference for Software User Assistance. He said the initial focus was a "discrete group interaction shared amongst selected friends and colleagues." Uses for the workplace could include collaborating on documents, brainstorming, translations, and tracking the progress of a issue.
The press release left the door open for possibly resuscitating it. But that's not likely. At least in terms of full support from Google for mainstream users. Possibly the technology may stay alive for software developers looking to embed its capabilities in applications. Most of the Wave discussions that I have browsed were managing tasks and projects among groups of collaborators. I think the technology could work well inside something like Google Docs.
WritersUA offers cutting-edge training and information to Technical Writers, Information Analysts and Architects, Documentation Designers, Help Authors, Publication Managers, Documentation Leads, Senior Writers and Documentation Contractors, and User Education Specialists. The focus is on software user assistance, which encompasses writing, editing, planning, coding, indexing, testing, programming, localization, and standards development.