The Logical Blog by IconLogic

Adobe RoboHelp: Merging TOCs

by Willam van Weelden, COTP For large help systems, it is common to reuse content in the Table of Contents (TOC) when part of the system uses the same options and/or features.  For instance, you might need to include a common introduction for several modules. With RoboHelp, you can include a topic in multiple locations in the TOC, allowing for easy reuse. Check out the image below. Notice that the Getting started topic is included in each of the four modules. If anything were to change within the common content, such as renaming a topic or adding a second topic, I would have to update the TOC in four locations. That is not just a lot of work, it is also a recipe for inconsistencies.

Fortunately, using RoboHelp’s multiple TOC feature, we can optimize the workflow by merging. Setting up a TOC for Merging On the Project Manager pod, open the Table of Contents folder. Then right-click the Table of Contents folder and choose New Table of Contents.

Give the new TOC a name and click OK. In this sample, I call mine Introduction.

The new TOC opens automatically. In the TOC, add the content that you want to share. In my case, it is just the Getting started topic.

Using the new TOC With the TOC set up with all common content, you can embed the new TOC. Go to the main TOC and select the location of the shared content. In my case, this is the Getting started topic. Click Insert TOC Placeholder at the top of the Table of Contents pod. On the Insert TOC Placeholder dialog box, select the Table of Contents you want to include. Then click OK to add a Placeholder.

Remove the common content from the TOC and then repeat these steps for every location where you want to include the common content.

Once you have set up the project, generate the output. For your reader, the TOC will look as if nothing happened. However, if you change the name of the topic, you only have a single TOC to update.

___   Willam van Weelden, COTP, is a technical writer and functional designer from the Netherlands. After studying to become a teacher, he made the switch to technical documentation.   Willam is an Adobe Community Professional, ranking him among the world's leading experts on RoboHelp. Willam's specialties are HTML5 and RoboHelp automation. Apart from RoboHelp, Willam also has experience with other industry standard programs such as Adobe Captivate and Adobe FrameMaker.

Adobe RoboHelp: Importing Google Docs

by Willam van Weelden, COTP  

As more companies make the move to Google products (over 5 million and counting), more content is created with Google Docs. This is understandable as Google Docs allows people to simultaneously work on documents and see each other's edits in real time. Personally, I use Google Docs all the time to make content reviews easier and avoid attachments in email.

When it comes to brining Google Docs into RoboHelp, there is a single downside: The documents reside on a Google server so you cannot directly import or link them into RoboHelp like you can with other content (like Word documents). Fortunately, you can download Google Docs to your computer and then import the downloaded content into RoboHelp.

Importing Google Docs into RoboHelp

1. Open your Google Docs document.
2. Choose File > Download as > Web page (.html, zipped).
3. Open the zip file and extract the file and images folder to a location of your choice.
4. Open a RoboHelp project.
5. Choose Project > Import > HTML.
   
   
    
6. Select the HTML file and click Open.

The document is now available as a topic. Assign the correct style sheet and update the topic as you see fit.

Tip: Are you planning on updating the Google Docs document? Or do you need fine control over how the document is converted to a topic? Export the Google Doc as a Word document. You can then leverage RoboHelp's Word integration for full formatting control.

***

Looking to learn Adobe RoboHelp? Come join me for my live, two-day online RoboHelp class (held once each month). And if you'd like to learn more about Dynamic Filters, check out my 3-hour mini course: Adobe RoboHelp: Advanced Content Reuse.

Adobe RoboHelp: Reuse a Customized Layout

by Willam van Weelden  

 

While customizing a Screen Layout in RoboHelp takes a lot of work (you have to add the images, assign the correct colors, etc.), you can get incredible results. Take, for example, the Responsive RedGreen layout, a customized Azure Blue provided by Adobe:

It is possible to reuse a customized Screen Layout in other RoboHelp projects. Here's how

Export a Customized Layout for Reuse

1. Open the Output Setup pod.
2. Right-click the Screen Layout and choose Export.
    
3. Select a location to save the Screen Layout and click Save.

The Output View pod will show a list of all files that have been exported. The Screen Layout gets an .slz extension.

Import a Customized Layout

To use the Customized Layout in another project, import it:

1. Open the Output Setup pod.
2. Right-click Screen Layouts and choose Import.
    
3. Select the Screen Layout you want to reuse and click Open. (The Screen Layout is imported and you can use it for your output.)
     

***

Looking to learn RoboHelp? Come join me for my live, two-day online RoboHelp class (held once each month). And if you'd like to learn more about Dynamic Filters, check out my 3-hour mini course: Adobe RoboHelp: Advanced Content Reuse.

Adobe RoboHelp: Custom Search Summaries

by Willam van Weelden  

 

When a reader searches for a topic in your RoboHelp output, RoboHelp shows a small preview of the topic, the so-called search summary:

 

By default, RoboHelp uses the first characters of your topic to automatically create these summaries. As you can see in the example above, the automatically generated search summaries do not give a useful description of the found content.

With RoboHelp 2015, you can provide custom search summaries through the topic comments. To set the search summary, open the topic properties and go to the Status tab. Fill your custom summary in the Comment field.

 

 

Once you have added a custom summary, you need to enable it in the Single Source Layout:

1. Open your Single Source Layout (Output > Generate)
2. Go to the Search section.
3. Select Use Topic Comment as Search Context.
   
    
    
4. Save and Generate the output.

Your output now uses the custom search summaries:

 

***

Looking to learn RoboHelp? Come join me for my live, two-day online RoboHelp class (held once each month). And if you'd like to learn more about Dynamic Filters, check out my 3-hour mini course: Adobe RoboHelp: Advanced Content Reuse.

Adobe RoboHelp: Adding Google Analytics to Topics

by Willam van Weelden  

 

Insight into the usage of your help content helps to identify difficult or incoherent policies, procedures or parts of your software. For example, if you notice that a specific instruction is used frequently, it may mean that the process is unclear. Otherwise readers wouldn't need to access your help so much.

 

Adobe offers RoboHelp server as an add-on product for tracking help usage. But you can also use Google Analytics. It offers fewer options but is completely free! Here are the steps to add Google Analytics tracking to your help content:

 

Create a Google Analytics Account

 

Before you get started, create a free Google Analytics account. Then follow these steps to set up your help site:

1. Go to the Admin page.
2. In Account, click the drop-down menu and choose Create new account.
   
     
3. Fill in the form and click Get Tracking ID.
4. Copy the Website Tracking code to your clipboard.
   
     

Add Google Analytics code to RoboHelp

 

Follow these steps to add the tracking code to RoboHelp:

1. Create a Master Page or open an existing Master Page. (Project > Pods > Output Setup > Master Pages)
2. Click Edit Footer to add a footer to the Master Page.
   
     
3. Switch to HTML view.
4. Paste the tracking code into the footer section.
   
    
5. Assign the Master Page to all topics.
6. Generate your output and place the help on a web server.

Once you place the help on a server, it may take up to two days before you will see tracking results. 

***

Looking to learn RoboHelp? Come join me for my live, two-day online RoboHelp class (held once each month). And if you'd like to learn more about Dynamic Filters, check out my 3-hour mini course: Adobe RoboHelp: Advanced Content Reuse.

Adobe RoboHelp: The User Defined Variable Converter Script

by Willam van Weelden 

 

User Defined Variables are a great way to manage content that appears frequently in your RoboHelp project. Variables allow you to change all occurrences of say, your company name in your project from a single location.

 

If you have already created a RoboHelp project but weren't aware of variables, you will be happy to learn that there is a script that quickly converts all occurrences of a word or phrase to a variable.

In my example below, I'm going to use the script to replace the word IconLogic shown below to a variable.

1. Make a backup of your project (this script will update your topics, and its better to be safe than sorry).
2. Choose Tools > Scripts > UDV Converter with UI.
3. In the Enter value to replace field, type a word or phrase. (I've entered IconLogic.)
4. In the Enter new UDV name field, add the name of the variable to be created. In this case, I used CompanyName.
5. In the Enter UDV value field, add a value for the variable. (In this case, I used the phrase IconLogic, Inc.)
   
     
    
6. Click Convert.

The script will go through the project and convert the text you indicated into a variable. In my example, the word IconLogic changed into the variable CompanyName. Because the value of the variable is IconLogic, Inc, that's the text users will see.

 

 

Note: When running the script, only topic content is updated. (You can see in the image above that the topic title in the tab is left unchanged). If you want to modify the title, you will have to manually apply the variable in the topic title. Also, if your variables aren't green, check out my article about showing variables in topics.

Adobe RoboHelp: Submit Sitemaps to Google

by Willam van Weelden  

 

I have already showed you how to create a sitemap for Responsive HTML5. After you create a sitemap, you need to tell search engines where they can find your sitemap so that they can use it to index your site. Here is how to submit your sitemap to Google:

Go to the Google Webmaster Tools page and log in using your Google account.

 

 

Click Add a site and, in the URL field, add the URL of the site that contains your Help system. (Target the root of the site. For example: http://www.example.com/help/.)

 

 

After clicking Continue, follow the steps to verify that you are the owner of the site.

Next, go to your dashboard and click Sitemaps. Then click Add/Test Sitemap.

 

 

Add the text sitemap.xml in the field and then click Submit Sitemap.

 

 

 

Click the link Refresh the page to refresh the status of the page and see whether your sitemap was successfully submitted.

The sitemap is submitted to Google and the search engine will index your help system.

 

 

***

Looking to learn RoboHelp? Come join me for my live, two-day online RoboHelp class (held once each month). And if you'd like to learn more about Dynamic Filters, check out my 3-hour mini course: Adobe RoboHelp: Advanced Content Reuse.

Adobe RoboHelp: Sitemaps

by Willam van Weelden  

 

RoboHelp 2015 patch 2 introduces a great feature for Responsive HTML5: sitemaps. A sitemap is a file with a list of all topics in your output. Search engines such as Google and Bing use the sitemap to determine which topics are available in your output, boosting findability of your content. If you want to make 1st place on Google, having a sitemap is essential. Without a sitemap, Google may not be able to index your entire output, skipping useful topics it can't find. 

 

Create a Sitemap

1. Open your RoboHelp project
   
   
2. Open the Outputs(SSL) pod. (Project > Pods > Outputs(SSL)).
    
3. Double-click your Responsive HTML5 SSL to open the properties.
    
4. From the options at the left, select Search.
   
     
    
5. At the right of the dialog box, select Generate XML Sitemap.
   
   
    
6. In the Base URL of the Help System field, add the URL where your content will be hosted.
   
   (For example, if your help will be hosted on http://example.com/help/<project name>, type the path without the project name, such as: http://example.com/help. RoboHelp will add the Output Folder name of your output.)
    
7. Choose how often your content changes with the Content Change Frequency drop-down menu.
    
8. Click Save and Generate to create your output.

Once you generate, RoboHelp will create the file sitemap.xml in your output. This file is the sitemap used by search engines. Provide this file to your webmaster (or submit the sitemap to search engines to allow them to index your site).

 

***

Looking to learn RoboHelp? Come join me for my live, two-day online RoboHelp class (held once each month). And if you'd like to learn more about Dynamic Filters, check out my new 3-hour mini course: Adobe RoboHelp: Advanced Content Reuse.

Adobe RoboHelp: Sitemaps

by Willam van Weelden  

 

RoboHelp 2015 patch 2 introduces a great feature for Responsive HTML5: sitemaps. A sitemap is a file with a list of all topics in your output. Search engines such as Google and Bing use the sitemap to determine which topics are available in your output, boosting findability of your content. If you want to make 1st place on Google, having a sitemap is essential. Without a sitemap, Google may not be able to index your entire output, skipping useful topics it can't find. 

 

Create a Sitemap

1. Open your RoboHelp project. 
   
   
2. Open the Outputs(SSL) pod. (Project > Pods > Outputs(SSL)).
    
3. Double-click your Responsive HTML5 SSL to open the properties.
   
   
4. From the options at the left, select Search.
   
     
   
   
5. At the right of the dialog box, select Generate XML Sitemap.
   
   
   
   
6. In the Base URL of the Help System field, add the URL where your content will be hosted.
   
   (For example, if your help will be hosted on http://example.com/help/<project name>, type the path without the project name, such as: http://example.com/help. RoboHelp will add the Output Folder name of your output.)
   
   
7. Choose how often your content changes with the Content Change Frequency drop-down menu.
   
   
8. Click Save and Generate to create your output.

Once you generate, RoboHelp will create the file sitemap.xml in your output. This file is the sitemap used by search engines. Provide this file to your webmaster (or submit the sitemap to search engines to allow them to index your site).

 

***

Looking to learn RoboHelp? Come join me for my live, two-day online RoboHelp class (held once each month). And if you'd like to learn more about Dynamic Filters, check out my new 3-hour mini course: Adobe RoboHelp: Advanced Content Reuse.

Development Corner: Image Formats

by Sally Cox  

When it comes to adding images to websites, PowerPoint presentations, or eLearning projects, you will likely be given JPEGs, GIFs, or PNGs. Let's review the three most common image formats and why/when to use them.

JPEG

JPEG is short for "Joint Photographer's Experts Group." It is one of the most popular formats used on the web and in eLearning. JPEG compression (the act of making the image as small as possible while retaining as much quality as possible) is "lossy" compression, which means every time you save an image as a JPEG, it loses quality.

 

The first image above is a JPEG taken with my iPhone. In the second image, I have opened the file in Photoshop and zoomed in on the child's face.

 

 

 

  

 

The little squares you see in the closeup image are called "pixels." Every time you save an image as a JPEG, it loses some quality by throwing out pixels. So if you are editing an image in Photoshop, always save it as the native format first, which is a PSD (Photoshop Document).

 

In the Save As dialog box in Photoshop, choose "Photoshop" as the file format. This saves as a PSD and preserves all details. Then after you finish your edits, do another Save As and choose "JPEG." The original PSD remains fully intact.

 

The image below is an example of the same photo saved multiple times as a low-quality JPEG. Notice that that there is a squarish effect happening and details are lost. This effect is known as "JPEG artifact."

 

 

 

JPEGs use the "RGB colorspace," which has more than 16 million colors. This allows for beautiful continuous-tone images with fluid gradations and a full range of colors. It's a good choice for continuous-tone, but does not allow transparency or animation.

GIF

The "Graphic Interchange Format" (GIF) works in the "Indexed colorspace," so its color palette is quite limited--just 256 colors. GIFs do, however, support transparency and animation (the once-hated animated GIF is making a comeback; I see it every day on Facebook). The oldest format on the web (created in 1989), GIFs are saved as "lossless" compression.

In the image below, I have saved the image as a GIF and it contains just 256 colors. You can see that the image has lost some of its detail.

 

 

Here is an example of an image containing just 8 colors--all detail is gone and the image has a "posterized" effect.

 

 

 

GIFs are perfect for "flat color," i.e., logos or flat design graphics that don't have gradations or continuous-tone (remember: only 256 colors). 

 

PNG

 

The "Portable Network Graphic" was created (approved as a web standard in 1996) to provide high quality continuous-tone but also allow for transparency and animation.

PNGs are saved in the RGB colorspace, so they have the full range of 16 million+ colors. What I like best about PNGs is the ability to save transparency, which I use every day in my workflow. I save my graphics as high-quality PNGs and allow transparency (a checkbox I choose in Adobe Illustrator when I export a graphic to PNG).

In a recent project I wanted to use an image of a headset, and I needed the background to be transparent. I opened the image in Adobe Illustrator and set the Export PNG options to High Quality and set the Background Color to Transparency.

 

 

 

Thanks to the Transparency option, I had the freedom to overlay the headset on the green background shown below.

 

To Recap:

	JPEG	GIF	"PNG"
COLORS	16 MILLION +	256	16 MILLION +
TRANSPARENCY	NO	YES	YES
ANIMATION	NO	YES	YES
CONTINUOUS-TONE	YES	NO	YES
FLAT COLOR	NO	YES	YES

 

***
If you'd like to attend some awesome 3-hour mini courses that focus on eLearning, check these out.