Help Authoring – Page 2 – The Logical Blog

April 25, 2014

User Assistance: HUDs in Technical Communication

by Tony Self

Did you ever see the 1986 movie "Top Gun?" If so, perhaps you recall seeing gun-sights, cross-hairs, warning messages, and air speeds displayed as green text on the cockpit windshield of the jets. What you saw in the movie was an early Head Up Display (HUD). If Top Gun is too old for you, how about Iron Man? HUD was featured prominently in that movie as well.

While HUDs may seem like something you'll find only in fighter jets or the movies, they are actually creeping into everyday life. For instance, HUDs are now installed as standard equipment in many cars displaying speed, distance, and messages onto the windshield. Drivers don't need to move their head up or down to read the text; they can keep looking straight ahead.

If your car isn't equipped with a HUD, you can use your smart phone, download a HUD app, place the phone on the dashboard, and reflect an inverted readout onto the windshield. And you can purchase HUD navigation systems (such as the unit shown below from Garmin).

Garmin HUD

There's a new type of HUD that's attracting lots of attention: Google Glass. Glass isn't the only product of its type on the market (there are dozens), but it attracts the most publicity. These wearable technology products display text in a tiny HUD in a pair of lens-less spectacles. The text displayed depends on the application; it could be the current time, an appointment, alerts… but it could also be procedural information, checklists, or product descriptions.

What does HUD technology have to do with technical communication? HUDs will provide innovative new ways to deliver technical information. For instance, Virgin Atlantic is currently testing Google Glass at Heathrow Airport. According to CNN, "The airline is conducting a six-week experiment with the wearable technology for passengers in its Upper Class Lounge at London. With data flashing before their eyes, staff can update customers on their latest flight information, as well as weather and events at their destination."

Google Glass being tested at Virgin Atlantic

Source: CNN

If the Virgin Atlantic tests prove successful, the opportunities for technical communicators are endless. Beyond simply documenting HUD devices and applications, technical documentation and eLearning content could actually be displayed on a HUD. There will be challenges of course. Writers looking to create content for HUDs will need to embrace writing techniques such as minimalism and separation of content and form. Nevertheless, it will be possible for technical communicators to one day deliver to this new media… a layer above reality.

April 4, 2014

Adobe RoboHelp: Master Pages for Word Headers and Footers

by Willam Van Weelden

When importing or generating Microsoft Word documents with RoboHelp, one of the chief weaknesses has always been the lack of support for Word's headers and footers. When importing, the Word headers and footers were ignored. When generating Printed Documentation, there was no support for controlling the resulting headers and footers from within RoboHelp. Instead, you had to edit them in the Word document.

With the new Adobe RoboHelp 11, you can now control the headers and footers for Printed documentation with Master Pages. This allows you to control the information displayed in the headers and footers of Word and PDF documents generated by RoboHelp.

A master page is a template for your topics. You can assign a style sheet to a master page, and set up headers and footers. If you apply a master page to a topic, the topic will use the style sheet and display the header and footer. When you create printed documentation, the printed documentation can use the header and footer you set up on the master page.

Setting up headers and footers in a Master Page

To change the header and footer of a master page, follow these steps:

Open the Project Set-up pod. (View > Pods > Project Set-up)
Open a master page (or create a new one)
Choose View > Header to open the header pane
Add content to the header just as you would add content to a topic
Choose View > Footer to open the footer pane
Add content to the footer, just as you would add content to a topic

Using the Master Page for Printed Documentation

Once you have set up the master page, you can use the master page when generating printed documentation.

Open the Single Source Layouts pod (View > Pods > Single Source Layouts).
Double-click a Printed Documentation layout to open the Print Document options.
From the Header/Footer area, select the master page you set up earlier.
Click Save and Generate to create the printed documentation.

***

Looking to learn RoboHelp? We offer a live, two-day online RoboHelp class once a month. Feel free to contact us to learn other ways to meet your RoboHelp training requirements.

February 4, 2014

Adobe RoboHelp 11: Responsive HTML5

by Kevin Siegel

When I teach my two-day Adobe RoboHelp class, students quickly learn that they need to generate a Layout (via the Single Source Layouts pod) before they can deliver usable Help content to their users.

During the class, attendees learn the strengths and weaknesses of each type of layout. For instance, they learn that WebHelp is excellent if users will be accessing the Help content over the internet and they're using computers running Windows or the Mac OS.

WebHelp, while offering excellent cross-platform and cross-browser support, does not support users who are using mobile devices such as the iPad or iPhone.

When Adobe released RoboHelp 10, one of the biggest innovations was Multiscreen HTML5. Since content generated using the Multiscreen HTML5 layout displays across mobile devices, Help authors can support all sorts of display sizes. The problem with Multiscreen HTML5 is that prior to generating the content, RoboHelp developers need to take the size of the user's display into account. In addition, customizing the look and feel of the Multiscreen HTML5 layouts isn't easy since you don't have access to an area like the WebHelp Skin Editor (which makes customizing a WebHelp skin a snap).

Adobe RoboHelp 11, which was just released a few weeks ago, added a new, very exciting layout to the Single Source Layouts pod: Responsive HTML5. With this layout, you don't have to take the variety of screen sizes users might use into account. If the user is viewing your content on a desktop, they will automatically see an appropriate arrangement of the screen components; if they view your content on an iPhone or Android phone, they will see the components resized and rearranged in a layout to best suit the smaller display size.

Here's how Responsive HTML5 works. First, visit the Single Source Layouts pod and double-click the Responsive HTML5 layout. The layout appears by default within new RoboHelp projects. In legacy projects that have been upgraded to RoboHelp 11, click the Create Layout tool (shown below). Select Responsive HTML5 from the Output type drop-down menu and click the OK button.

Similar to WebHelp, you can specify an initial look and feel for your Responsive HTML5 layout by clicking the Gallery button.

There are two designs in the Gallery area and you can download more via the link at the right of the dialog box. In addition, as you'll see in a moment, you can easily customize the layout.

After selecting a layout from the Gallery, you will be presented with a series of screens that allow you to easily customize many components that make up the original design. What I really like about this area is that the Adobe engineers have labelled everything so you know what each area controls.

Generate the layout and it will open in your default web browser like WebHelp, FlashHelp, or Multiscreen HTML5. In the image below, I'm viewing the Responsive HTML5 output on a desktop computer and the display is pretty large. With a larger workspace, notice that there is a navigation area at the left of the browser window.

In the image below, I've resized my browser window to a size more appropriate for a tablet (such as the iPad, Kindle Fire or Microsoft Surface). Notice that the navigation icons have bounced to the right, responding automatically to the size of my display.

And in the image below, I've resized my Help window again. This time the navigation icons have dropped to the bottom of my display.

As I continued to resize the browser to simulate various screen displays, the icons got smaller and were positioned appropriately for the size of the display.

Adobe RoboHelp 11: Responsive HTML5 on a small display.

Of all the layouts I've used in RoboHelp over the years, I firmly believe that Responsive HTML5 is the absolute top of the mark. While WebHelp is currently the industry standard when it comes to generating Single Source Layouts, I expect Responsive HTML5 to vault into the top spot very quickly.

***

Looking for training on Adobe RoboHelp? IconLogic offers live, online Adobe RoboHelp classes each month for both RoboHelp 10 and the new RoboHelp 11. We can also bring the same great training onsite to your facility. Interested? Contact us for details.

January 22, 2014

Adobe RoboHelp 11: Sharing Resources via Dropbox

by Kevin Siegel

Adobe released Adobe RoboHelp 11 last week. Over the next few weeks, I'll be covering some of hottest new features. This week: sharing resources via the Cloud (specifically, with Dropbox).

Sharing resources isn't a new concept in RoboHelp. In fact, the Resource Manager pod has been around for the past few versions of RoboHelp. What's new in RoboHelp 11 is the ability to specify a Dropbox as a folder on the Resource Manager.

To begin, visited Dropbox.com and created an account. I also created a folder in Dropbox and set it up as a share object (both tasks, creating and sharing the folder, were simple and took mere seconds).

Once my Dropbox account had been set up, I started RoboHelp 11 and chose View > Pods > Resource Manager. From the top of the Resource Manager pod, I clicked the Add Shared Location tool.

In the Add Shared Location dialog box, I clicked theLocation type drop-down menu and selected Dropbox. (Each time I've performed this step over the past few weeks, RoboHelp has consistently loaded my Dropbox folder and Path for me. Alternatively, you can click the Browse button and manually locate your Dropbox folder.)

The next step was to add content to my shared Dropbox folder on the RoboHelp Resource Manager. My shared Dropbox folder is called SharedRoboHelpTopics. When I dragged a topic (Alcohol_Policy) to the shared folder, I was delighted to see that in addition to the topic, the Cascading Style Sheet being used by the topic (policies.css) was also added to the shared folder.

One of my team members (Biff Bifferson), who is located in another state, was working on a RoboHelp project and needed to use some of my content. While we don't share a network connection, we both have Dropbox accounts. I accessed my Dropbox account and sent Biff an invite to my SharedRoboHelpTopics folder.

Biff checked his email and added the SharedRoboHelpTopics folder to his Dropbox. Biff then used RoboHelp's Resource Manager pod to add his Dropbox as a Shared Location.

Since his Dropbox included my shared folder, Biff's Resource Manager immediately displayed my shared resources.

To add my shared content to his RoboHelp project, Biff right-clicked the Alcohol_Policy topic on the Resource Manager pod and chose Add to Project.

Like magic, my content was now being used in two projects in two different locations. What do you think? Cool?

But then… then… I edited the topic on my computer. (I know, crazy right?)

My Resource Manager alerted me that my shared assets weren't synchronized (via the red icon shown in the image below). When content isn't synchronized, it's likely that team members aren't using the same content.

Because I wanted to ensure that both Biff and I were working with the same assets, I right-clicked the topic on my Resources Manager and selected Sync.

Green check marks indicated that all was well between the content in my RoboHelp project and the assets in my Dropbox. But I was curious to learn if Biff actually got the updated content in his project. And if so, what was his experience? Was it painful?

It turns out that Biff's experience was almost, well, routine. He told me that when he opened his project with RoboHelp 11 later that day, he was greeted with the Linked Resource Notification dialog box shown below. All he had to do was click the Update button and his content was automatically synchronized with mine. In a word… that's awesome!

***

December 5, 2013

Adobe RoboHelp: Favicons

by Kevin Siegel

During my online RoboHelp classes, students frequently ask for ways to brand a generated WebHelp layout. There are multiple ways to add a corporate identity to a layout including customizing a WebHelp skin and adding a copyright notice within the footer of a master page.

While working with skins and master pages is easy enough, one of the fastest ways to brand WebHelp is also the easiest: add a Favicon. A Favicon is an icon that appears in a browser's address bar or next to the site name in a bookmark list. In the image below, you can see the title of a generated layout (Technical Communications) as it appears in a Firefox tab. Just to the left of the title is a generic Favicon.

To add your logo as a Favicon, show the Properties of a RoboHelp WebHelp layout (on the Single Source Layouts pod, right-click a WebHelp layout and choose Properties).

Select the General category and you'll find the Favicon field just below the Title Bar field.

Adobe RoboHelp: Favicon field

Click the Browse button and open the Favicon image you'd like to use. In the image below, I've loaded a Favicon I created called IcoFile.ico. You can use png, ico, or gif images as Favicons.

Adobe RoboHelp: ICO file loaded as a Favicon.

Generate the layout and view the results. You'll see your corporate Favicon in the tab or title bar of the web page in place of the default image.

***

Looking for training on Adobe RoboHelp? IconLogic offers live, online Adobe RoboHelp classes each month.

November 24, 2013

Technical Communications: Writer Challenges in Agile and Traditional Development Teams, Part II

by Alyssa Fox

Last week I introduced you to agile, an increasingly popular development method primarily used by software companies. This week I'm going to cover how agile helps you get more thorough and timely reviews of your documentation from the team.

Getting Helpful Documentation Reviews

Whether you are in a traditional or agile development environment, getting valuable, informative edits on documentation you send out for review can be like pulling teeth. Some reviewers give the documentation a cursory glance and declare it "okay" with no helpful comments. Others fail to follow the steps as listed in the documentation when testing procedures and have no way to ensure the writer captured everything accurately.

When the Information Development team in my organization used the waterfall process, we used a review cycle that included three drafts of each book: a first draft, an approval draft, and a quality edit draft. The first draft and quality edit draft were internal to our Information Development (ID) department. All of these drafts happened toward the end of a software release cycle and were not reviewed by anyone outside the ID team until the project was feature complete and all features were documented in one fell swoop. Unfortunately, the time when we sent out our approval draft for review by other functional areas often coincided with their busiest times of the release cycle–testing the product and fixing bugs. Because of this poor timing for the documentation review, we often got only superficial edits, or no comments at all, which didn't help us improve the documentation quality.

In agile development, we now write documentation for a feature in the sprint (time-limited development cycle) in which it is developed and tested. For additional information about agile concepts, see Fiona Hanington's article, Can I Be an Agile Technical Communicator When My Team Is Not?.

On more mature products, we no longer send out the entire book as a first draft for ID review. Each time a feature is documented, that documentation must be reviewed by the ID lead/manager and by QE for technical accuracy before the team can close the user story. This idea is similar to a daily in filmmaking–use it to do a quick gut check to see if everything looks okay or if something needs to be redone. We still send out approval drafts for some projects; but for most reviewers, at that point it is simply a director's cut or a chance for them to see the book in its entirety.

Next time, we'll wrap up with how agile helps spread writers' workloads throughout the release cycle.

Note: This article was originally published earlier this year on the TechWhirl website.

November 19, 2013

Adobe RoboHelp: Using Images in Variables

by Willam Van Weelden

Variable sets, which I've written about previously, allow you to define groups of definitions for a variable which allows you to easily support differently branded products from a single RoboHelp project. This week I want to show you another cool variables feature: images.

You can easily reuse images in multiple RoboHelp topics. Since the images that appear in the topics are linked externally to the original image, when you edit the original image, all of the RoboHelp topics are updated automatically. One drawback to this global update is that it only works if you use the same image in all of the generated layouts.

You can make your life even easier by adding images to variables. Take a logo for example. Many customers require that their software is personalized. For example, the application must use the client's brand colors and logo. By adding a logo to a variable and using variable sets, you can easily change the branding used in your Help content.

Add an Image to a Variable

Open the User Defined Variables pod. (View > Pods > User Defined Variables).
Select a variable (in the image below, I've selected a variable that I created called Logo).
Choose Insert > Image.
Select an image and then click OK.

The image is added to the variable. At this point, you can use the variable within any topic, just like a typical variable.

Adobe RoboHelp: Image added to a variable

***

Looking to learn RoboHelp? We offer a live, two-day online RoboHelp class once a month. Feel free to contact us to learn other ways to meet your RoboHelp training requirements.

November 17, 2013

Technical Communications: Writer Challenges in Agile and Traditional Development Teams

by Alyssa Fox

Technical communicators have historically faced several challenges when working on development teams. From not receiving the information needed to do their jobs, to ensuring their work estimates are included in the overall team's estimates, to showing their value to stakeholders, writers on project teams can feel like they are facing an uphill battle to create good documentation. A number of factors can influence how these challenges manifest during product development, including organizational culture and various business needs, and the agile development approach can help.

Agile is an increasingly popular development method primarily used by software companies. Its iterative nature and focus on the self-directed team support writers in recognizing and learning to rise to the challenges common to most development teams.

This three-part series discusses those challenges, and shows why agile can be the better approach for technical communicators.

Being an Equal Part of the Team

Most technical writers with more than a few years' experience under their belts can empathize with the struggle to be included as an equal member of the project team. The business case for this model is simple and common sense: Being treated as a vital part of the team leads to increased communication with other team members, inclusion in essential meetings, and improved product knowledge-all of which contribute to better, more effective documentation and user support.

Regardless of the type of development environment you are in, to be an equal player, the onus is on you. Take the initiative: speak up in meetings, request invitations to those meetings, and offer feedback. In other words, get involved in all aspects of the product development. This level of involvement tunes you into the project from the beginning, with obvious benefits: knowing the requirements, design, and thought process behind the design of the software. Ask lots of questions–lots and lots of questions–but make them count. If you hear something in a design meeting that doesn't make sense to you, or you think there's a better approach, say so. Don't be intimidated by the fact that you're not a developer–chances are the product manager and the marketing team know less about code than you do.

Remember, it's the technical communicator's job to look at the product from the user perspective. If you find a user interface is difficult or confusing, so will users. You have an obligation to provide that feedback to the developer who's coding it.

To be an equal partner on the engineering team, you must own the work with the same level of commitment as developers, analysts, or testers. Claim ownership of the technical accuracy of the documentation you write. Don't write just what the developers tell you to write or assume something works a certain way. Work with the builds, ask questions, and gain your own understanding of how the product works. That means speaking up to get access and then maintaining whatever virtual machines or environments you need so you can quickly and easily access the product. If you demonstrate a solid understanding of the product, the team trusts you more when you point out a technical or usability problem and make a suggestion for change.

Agile development focuses heavily on communication. The feature requirements, use cases, and test plans of a waterfall environment translate to user stories, acceptance criteria, and acceptance tests in an agile world. An agile process uses significantly less project documentation, with the idea that the communication going on among the team members is enhanced through several different types of meetings. While the number of meetings might seem overwhelming at first, it quickly becomes apparent how crucial they are for open discussion about the user stories and planning items the team is working on. Become more visible by participating in these meetings and you'll gain both the trust of your team members and more product knowledge. That product knowledge directly feeds in to you producing higher-quality content that provides information that users really want.

Next time, we'll discuss how agile helps you get more thorough and timely reviews of your documentation from the team.

Note: This article was originally published earlier this year on the TechWhirl site.

August 26, 2013

Adobe RoboHelp: Embed Captivate HTML5 Output

by Willam Van Weelden

Adobe Captivate 6 introduced HTML5 output, allowing eLearning content to be interactive on mobile devices such as the iPhone and iPad. By combining Captivate's and RoboHelp's HTML5 outputs, you can easily support interactivity for iPhones and iPad in your help system. Currently only RoboHelp's Multiscreen HTML5 output supports Captivate's HTML5 output. Other outputs, such as WebHelp, only support Captivate's Flash output.

Embed Captivate HTML5 Content Within RoboHelp

Publish your Captivate demo as both Flash and HTML5.
Create or open a RoboHelp project.
Open the topic where you want to add the demo.
Choose Insert > Adobe Captivate Demo.
In the Multimedia Name field, open the swf you published from Captivate.
In the HTML5 output field, select the index.html you published from Captivate.
Click the OK button.

By default, RoboHelp uses the Captivate Flash output when you generate the layout. To allow RoboHelp to use Captivate's HTML5 output, you need to make a small change to the Multiscreen HTML5 Single Source Layout.

Open the Multiscreen HTML5 Layout in the Single Source Layouts Pod. (View > Pods > Single Source Layouts).
Open the Optimization settings of your desired Screen Profile(s).
Select Use Adobe Captivate HTML5 output.
Click the Save button.

When you generate the Multiscreen HTML5 layout, the layout will now use Captivate's HTML5 output whenever it is available.

***

Looking to learn RoboHelp? We offer a live, two-day online RoboHelp class once each month. Feel free to contact us to learn other ways to meet your RoboHelp training requirements.

August 9, 2013

Adobe RoboHelp: Using SharePoint for Version Control

by Willam Van Weelden

In a previous article I showed you how you can use SharePoint to host a shared review. You'll be happy to learn that with RoboHelp 10, you can also use SharePoint for version control. Version control is a method by which you store all project files on a server. You work with a local copy and synchronize all changes with the server. The benefits of using version control include:

Version history: the server makes a new version of topics for every change. This allows you to retrieve old versions right from your RoboHelp Project.
Multiple authors: multiple authors can work with the same project simultaneously.
No more backups: the server does that for you.

Prepare SharePoint for Version Control

On the SharePoint site, add a new library. Enable version control for the library and require files to be checked out before editing. You can choose to use either minor or major versions. All reviewers must have edit permissions for the library. Your SharePoint administrator can help you with this.

Add a RoboHelp Project to Version Control

Open or create a RoboHelp project.
Choose File > Version Control > Add to version control.
In the Select Version Control Provider dialog box, select RoboHelp SharePoint Connector and click the OK button.
In the Connection Details dialog box, add the URL of the SharePoint site in the SharePoint Site field (and then click the OK button).
Choose a library to use for the version control.
Select a folder in the library (or create a new folder) and click the OK button.
Click the Yes button to add all of your RoboHelp project files to the SharePoint library.

Adding files to the SharePoint library could take time initially. However, once the files are added, you should not see any performance issues. To enable the version control toolbar for easy check-in and check-out, choose View > Toolbars > Version Control.

Want to know more about working with version control? Click here.

***

Looking to learn RoboHelp? We offer a live, two-day online RoboHelp class once each month. Feel free to contact us to learn other ways to meet your RoboHelp training requirements.