The Logical Blog by IconLogic

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.

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.

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.

Adobe RoboHelp: Variable Sets

by Willam Van Weelden

I've previously shown you how to use variables in topic titles. As discussed in that article, variables allow you to quickly update text throughout a project. For example, variables are particularly handy should your boss decide to rebrand the project two days before your deadline.

RoboHelp also supports variable sets, which are alternative definitions for your variables. For example: a company markets the same product in different sectors, private and public. In the private sector, the product is called ACME; in the public sector the product is called EMCA. It's the same product, just a few naming differences. You use the same help output for both sectors. Before you publish, you just need to set the product name correctly using variables.

Using variable sets, you first define a single set of variables. Then you create alternative definitions for only those variables that need to be changed. When you generate the output, you simply choose which variable sets to use, allowing you to set the alternative product name a single time.

Creating a Variable Set

1. Open the User Defined Variables pod. (View > Pods > User Defined Variables)
2. Click the Add/Edit/Delete Variable Set button.
   
3. Click the Add button and name the variable set.
   
4. Click the OK button to close the dialog box.
5. Select the variable set from the drop-down menu and change the values as needed.
   

Generating a Layout With a Variable Set

Prior to generating the layout, you simply need to choose the variable set from the Variable Set drop-down menu. (For WebHelp, the Variable Set drop-down menu can be found in the Content Categories area.)

***

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.

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.

Adobe RoboHelp: Variables in Topic Titles

by Willam Van Weelden

User Defined Variables have been a RoboHelp staple for a few years now. You were first introduced to variables in this 2009 IconLogic blog post. As a review, variables are placeholders for text that you need to use throughout a RoboHelp project (e.g.: a product name). You might be using the product name thousands of times within hundreds of RoboHelp topics. Should you need to change the name of the product, you would have to go through the entire project and manually change the product name, one-by-one (or use RoboHelp's Find/Change feature).

As an alternative to manually adding the product name throughout a project and then having to worry about manually updating the text later, you can create a variable. The variable will display the product name as if it were regular text, and insert the variable within topics, snippets, the Table of Contents (TOC), and/or the Index. Should the product name need to be changed, edit the variable text via the Variables pod and it will be updated everywhere. It's a powerful feature and very easy to use.

In this article, I want to show you a fantastic enhancement to variables that was introduced in Adobe RoboHelp 10: the ability to add variables within Topic Titles.

In older versions of RoboHelp, a Topic Title was static text, meaning that you had to manually type the Topic Title when you created the topic. If you added the topic to the TOC, the Topic Title appeared on the TOC. But since the Topic Title was static, a change to the Topic Title when editing the Properties of the topic meant that you also needed to edit the text that appeared on the TOC. The ability to add a variable within the Topic Title means the text will be linked to the Topic Properties and will automatically update everywhere.

Add a Variable Within a Topic Title

1. After you've created the variable, display a topic's Properties dialog box. (You can display the Properties dialog box for the topic via the Topic List pod by right-clicking the topic.)
2. On the General tab, click the Variables drop-down menu and and select a variable.
   
3. In the Topic Title field, select the location where you want to insert the variable.
4. Click the Insert button.
   

Now that the topic's Title is using a variable, should you update the variable at any time, the variable text will update within the topic text, title, Index and the TOC.

***

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.

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

1. Publish your Captivate demo as both Flash and HTML5.
   
2. Create or open a RoboHelp project.
3. Open the topic where you want to add the demo.
4. Choose Insert > Adobe Captivate Demo.
5. In the Multimedia Name field, open the swf you published from Captivate.
6. In the HTML5 output field, select the index.html you published from Captivate.
   
7. 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.

1. Open the Multiscreen HTML5 Layout in the Single Source Layouts Pod. (View > Pods > Single Source Layouts).
2. Open the Optimization settings of your desired Screen Profile(s).
3. Select Use Adobe Captivate HTML5 output.
   
4. 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.

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

1. Open or create a RoboHelp project.
2. Choose File > Version Control > Add to version control.
3. In the Select Version Control Provider dialog box, select RoboHelp SharePoint Connector and click the OK button.
   
4. In the Connection Details dialog box, add the URL of the SharePoint site in the SharePoint Site field (and then click the OK button).
   
5. Choose a library to use for the version control.
6. Select a folder in the library (or create a new folder) and click the OK button.
   
7. 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.