Some days back, I had blogged about the two sample projects that come with Adobe RoboHelp 9. While the primary purpose of these projects is to demonstrate some of the new and old features of RoboHelp, these projects also exemplify some cool best practices for authoring in RoboHelp.
Use of cross-hatching to indicate that a topic/text has CBTs applied
Using the View > Show > Conditional Areas option, the sample projects display CBT-applied topics or text with cross-hatch shading.
Cross-hatching to easily identify CBT-applied topics
See Hide and view conditional text for more information.
Use of DHTML drop-downs to reveal information on demand
The sample projects include several tips. Some of the tips are “hidden” in the output by using DHTML drop-downs. Only the tip icon appears in the output to minimize distraction, and users need to click the icon to reveal the information. The same technique has been applied to show information about entitlement, procedure, and disputes related to dependants’ leaves.
Extra information "hidden"
Extra information displayed "on demand"
See Dynamic HTML and special effects for more information.
We recommend that you play with the sample projects and discover many more best practices. Check out how you can use user-defined variables and snippets to enhance productivity and ensure consistency. Check out how you can use master pages to add branding and copyright information to each page of your Help system.
While scanning through bugs and user comments on the RoboHelp documentation, we stopped at this one the other day. A seemingly innocent instruction like “Open the Table Of Contents pod.”, we found, had made a user very very angry. It seemed that the user had wasted hours trying to find out how to open the TOC pod.
I remembered reading a reviewer’s comment that new RoboHelp users find it difficult to locate the Table of Contents folder in the Project Manager pod, especially if they open a big legacy project and the Project Files folder is expanded.
When you locate the Table of Contents folder in the Project Manager pod, you can either expand it to access existing TOCs or right-click to select the New Table of Contents option. The TOC you open or create is displayed in the Table of Contents pod.
Yes, you can create multiple TOCs – for different audiences. For more information, see this Help topic.
Steps to autocreate a TOC
- In Project Manager, right-click the Table of Contents folder, and select New Table Of Contents.
- Specify a name for the TOC.
- (Optional) Select Copy Existing Table of Contents and browse for an existing TOC file (.hhc) to create the TOC from an available TOC.
- Click OK. RoboHelp opens the Table Of Contents pod.
- In the Table Of Contents pod, click the Auto-Create TOC button.
- Select an option in the Auto-Create TOC dialog box:
- Delete Current TOC Before Creating New – Removes books and pages before automatically creating the table of contents. If this option is deselected, existing books and pages are included in the table of contents.
- Create TOC Pages For Mid-Topic Links – Creates pages in the table of contents based on bookmarks. RoboHelp makes the topic that contains the bookmark into a book and all bookmarks into pages.
Remember that the table of contents is a hierarchy of the folders, topics, and any subfolders in Project Manager. In other words, if the Project Files folder structure is flat, the autocreated TOC will be flat too.
Before you start creating your first TOC, try this interactive demo. The demo shows how to create a TOC manually.
If you want to exclude any topic from being searched in WebHelp, FlashHelp, or Adobe AIR output, all you need to do in RoboHelp 8 is select the Exclude From Search option in topic properties.
Although the topic appears in the Table of Contents, the topic is not searched.
How to exclude topics from search in CHM output
Using the Exclude From Search option does not work in CHM output. There’s always a workaround though as you’ll find in this forum thread.
How to exclude topics from search in earlier versions
If you use an earlier version of RoboHelp, you can still exclude topics from search, using a Conditional Build Tag, say ‘Exclude_from_Search’. The procedure is documented here.
As I said, RoboHelp 8 makes excluding topics from search easy!
Late last month, we created small brochures of RoboHelp, FrameMaker, and Acrobat tips for the STC India Conference attendees.
Download the RoboHelp brochure from here.
My colleague Samartha Vashishtha has shared the FrameMaker and Acrobat brochures on his site.
Some days back, I spotted a tweet by Tom Johnson announcing his new post – Podcast on the Seven Deadly Sins of Blogging. I know that I have been a sinner, not having updated my blog for over a month.
Nowadays, I spend a good part of my day keeping an eye on my Twitter home. My primary intent is to play the information facilitator for RoboHelp, the Adobe product I document. Twitter gives me the means to shout out updates, new tools, hidden features, and events.
I follow the power users of RoboHelp on Twitter and easily get information when they post new content on the web. My job then is to map that content to core Help topics and add the links so that other users can benefit from this supplementary content.
Step 1: Spot the announcement of a useful post.
Step 2: Identify the relevant topic in Help and add a link to the post.
Step 3: Tweet about the Help update.
Twitter gets me thinking – in different directions. Every now and then, I get derailed and something non-RoboHelp catches my attention. I spot ‘cloud computing’ and become curious to find out about what the world is thinking about documentation for SaaS applications.
Johnson’s posts reassured me that these occasional detours are a necessary part of the social networking experience that we are seeking as corporate tweeters and bloggers. They broaden our interests, update us on the trends, and prepare us to create relevant and interesting posts (being irrelevant and being boring are two of the seven sins Johnson talks about).
You can check out Johnson’s blog for the other five sins. Meanwhile, what are the seven deadly sins of tweeting?
With RoboHelp, you can automatically generate mini TOCs in long articles with many subsections.
Here’s Benny Joseph, my colleague at Adobe and a RoboHelp pro, on when to use the mini TOC placeholder and how:
Consider the following when you create and apply master pages with mini TOC in your RoboHelp project:
Need for mini TOC: Many topics could contain only one coherent topic, which does not require structuring through sub headings or bookmarks within the topic. For such topics, a mini TOC might not be required. You can create a separate master page without the mini TOC placeholder and apply it to such topics to avoid the mini TOC from appearing.
Topic Length: If your article is a large topic with many subsections, the mini TOC could appear long and nested. In such cases, try to restructure and divide the content and in multiple topics. For example, if you use lower heading levels such as Heading 5 and Heading 6 to highlight definition lists, try to bunch them under a higher level heading, and apply paragraph styles other than heading styles.
Number of levels: RoboHelp includes heading levels 2 through 6 in the mini TOC by default. However, if the topics have a large number of lower-level heading styles, the mini TOCs generated on these pages can become long and deeply nested. To avoid this, limit the number of levels in the mini TOC to have a shorter mini TOC that gives a quick overview of your topic contents.
Placement: Even though you can place a mini TOC placeholder in a topic or a master page, use the master page option if your project is large or you are updating an existing project. Inserting a mini TOC placeholder in each topic can be time-consuming, whereas you can apply a master page with a mini TOC placeholder to large projects at one go.
If you refer to Adobe documentation on the web, you know you can sign in with your Adobe ID and add your comments to any Help topic. Experts designated as moderators answer your queries.
With the release of Adobe Community Publishing 1.1 beta, Adobe has taken another huge step in encouraging community participation.
Community members can contribute tips, movies, code snippets and more with easy-to-use templates. Contributions are moderated by community experts. Plus, everyone in the community can rate and comment on contributions.
To add a contribution, follow these steps:
- Download the Community Publishing app: http://www.adobe.com/community/publishing/download.html
- Author your tip using a simple template
- Publish it to adobe.com
Content goes live within minutes and is automatically added to community help search.
Check out this useful tip added recently by RoboHelp moderator Peter Grainge.
For all tips, see http://www.adobe.com/community/publishing.