Technical Communication Suite Keyboard Shortcuts 23rd November 2009 (Monday)
Posted by Colum McAndrew in Acrobat Professional, Adobe, Captivate, FrameMaker, RoboHelp, Technical Communication Suite.add a comment
I know that they are not everyone’s cup of tea but give me a keyboard shortcut any day over a mouse click. Maybe it’s an author thing but if I am typing anyway, why move your hands away from the keyboard to do something. Provided it doesn’t require a form of digit dexterity only found in aspiring Houdini impersonators, sock it to me.
When it comes to the various packages in Abobe’s Technical Communication Suite the keyboard shortcuts are well documented just not all in the help. I’ve seen various posts in the past detailing the shortcuts for one or other of the suite’s packages but not for all. That is until now. Kevin Speigal’s, co-founder of Icon Logic, has written helpful features on his blog listing all the keyboard shortcuts for each of the main four applications that make up the Technical Communication Suite. Check them out.
Help documentation on Channel 85! 19th November 2009 (Thursday)
Posted by Colum McAndrew in Captivate, Technical Writing.4 comments
Anyone who knows me well will tell you, I am a big football fan. No not the “football” where the ball only rarely touches a player’s foot (well OK I am a fan of it) but the European and more accurately named variety ;-) My team, AFC Wimbledon, will need no introduction to true football (soccer) fans as its model is based on a club owned and run by the fans. Just like FC Barcelona except without the bulging trophy cabinet and multi-million pound turnover!
As a regular contributor to various club fanzines I was struck but a comment made by another contributor and AFC Wimbledon fan, Ian McNay. Ian is Chair of Cherry Red Records, a record company based in the United Kingdom. He recently set up a TV station for the club that features game highlights, interviews with key club figures and post match analysis. However really caught my eye was his vision for the future. He says, “Within a few years all decent websites will be mini television stations.”
This got my thinking of the other part of my life that is not devoted to football reporting. Could not the same be said of documentation? Especially as I was sent a Tweet recently suggesting that I embed occasional Captivate movies in this blog. Excellent idea I thought, and follows on from my day job where my team has recorded and embedded Captivate files inside the help. It has proved a real vote winner internally and will surely have a similarly positive response once our user base gets hold of it.
It is a vision at our company to change the overall user experience of using our product documentation. Gone are the days when we produced flat, dry manuals and help files. We are moving to a much greater level of interaction. The first step of which is the Captivate movies inside the help documentation that is itself hosted online. This has the added benefit that we can email users the URL to specific help topics to help solve their queries when they contact us. We have a LinkedIn User group for customers to discuss more general application issues. We also plan to have other internal product forums for a more immediate response.
The documentation though is a real area of interest for me. My experience of using help files is that they often only go so far. They are written with a specific audience in mind and normally have to be fairly generic by nature. As such they may tell me how to do something but not how I could use that knowledge to make better use of the software. Wouldn’t it be great if the help could also be a living, breathing documentation source where users can add links to blogs, wikis, websites and the like that would add to the overall user experience.
Adobe is already doing this with the Adobe Air applications built into their applications. You can add comments to a help topic that once approved appear for all and sundry to see. Just imagine the power of a help file if it not only told you how to do something, but also contained links to useful resources demonstrating how others were using it. There really is no end to the possibilities that such functionality offers. Adobe is working on full integration with Adobe Air in RoboHelp and other products, and I for one can’t wait.
So the aim is a help file that acts as a portal to other useful information. As a Technical Writer my role will change. A television presenter I may not be but having the responsibility for being a moderator of a truly interactive, useful help environment? I could do that.
Alphabetti Spaghetti 18th November 2009 (Wednesday)
Posted by Colum McAndrew in Adobe, RoboHelp.2 comments
A short while ago, the question was asked on the RoboHelp forums how to organise snippets so that they appeared in alphabetical order. This should not be a problem for you if you don’t have many snippets or are using RoboHelp 8. If, like me, you only have 4-5 snippets in any one project, whether they are displayed alphabetically is neither here nor there as the pod is way big enough to display them and they are easy to find.
Likewise users of RoboHelp 8 will know that snippets are automatically sorted alphabetically. It looks like users of RoboHelp 7 however do not have this functionality. So if you are on this version and use snippets in a big way, I can see how having to hunt through a list to find the one you want would be problematic.
You can of course manually sort your snippets inside their pod. Just right click on a snippet to display a popup menu from which you can move an item up or down one position in the snippet list. Trouble is, you have to repeat this over and over if the snippet needs to be moved more than one position. Also if you have lots of snippets this can lead to a lot of frustration to get things just the way you want. There has to be an easier way.
Thanks to the RoboWizzard, Rick Stone, who uncovered exactly where RoboHelp 7 stored the snippet information, there is. The answer lies in the Windows registry. Of course there are risks with doing anything with this so be warned. Don’t do anything in the registry without taking a backup and being 100% sure you know what you are doing. If you look in the HKEY_CURRENT_USER\Software\Adobe\RoboHTML\7.00\Components\36 location you should find a set of keys that map to your RoboHelp projects. If you click on a project, you will see the snippets used inside it. You can rearrange them by changing their name to something like Name0, Name1, Name2, etc.
BTW for the benefit of those outside the UK who may be wondering where Alphabetti Spaghetti in the title comes from, it was (and indeed may still be?) a food targeted at the young generation and students! Based on tins of baked beans, it was little pieces of spaghetti shaped in the shapes of the alphabet in tomato sauce. Trouble was, you used to spend so long arranging the damn things around your plate to spell words that by the time you ate them they were cold!
Definition of “Average” 17th November 2009 (Tuesday)
Posted by Colum McAndrew in Language.4 comments
I’ve been working of late with some documentation related to equations used by an analytical software package. Cue lots of mathematical symbols. Brain ache! During this exercise in torture I came across the following definition for the mathematical function otherwise known as Average:
“A representative figure that is used to give some impression of the size of all the items in a given population. This is a measure of central tendency. By this we mean that while a population may range in values, these values will be distributed around a central point. This central point is therefore in some way representative of the population as a whole. Averages are also known as measures of location, because they show roughly where data are located on a scale of values.”
Technically accurate but so far off the scale of use of succinct language LOL! Now what is the website of the Plain English Society?
Viewing WebHelp Pro & FlashHelp Pro output in RoboHelp 13th November 2009 (Friday)
Posted by Colum McAndrew in Adobe, RoboHelp, RoboHelp Server.add a comment
One of the minor irritations of using WebHelp Pro or FlashHelp Pro outputs from a RoboHelp project used to be the workflow you had to run through to check the output as it appears on the server. Once you had published your output to the server, you had to open a browser and type in the URL of the Web Administrator. Only then could you logon and display the project.
All of this has changed with the arrival of RoboHelp 8. This version has a RoboHelp Server pod that can be displayed via the View > Pods menu item. When the pod is first displayed, a “Setup” button is displayed which when clicked allows you to enter the path and name of the RoboHelp Server. Once set, a “Connect Now” button allows you to view the project’s published output.
Tip:
It is a good idea to size the pod to a size that comfortably displays the Web Administrator dialog and save your environment via the File > Environment > Save Environment menu item. If you don’t do this, you’ll have to manually resize the pod each time it is opened.
Grammar Obsessive Disorder 12th November 2009 (Thursday)
Posted by Colum McAndrew in Language.add a comment
My goodness. Do I really suffer from Grammar Obsessive Disorder? Check this out. It had me in tears. LOL!
Top 10 Technical Writer annoyances 12th November 2009 (Thursday)
Posted by Colum McAndrew in Technical Writing.Tags: Annoyances
13 comments
The life of a Technical Writer is far from boring. Days spent typing away at a keyboard are often disturbed by the rigours of the corporate world. I was reminded of this earlier today when one of my team, a relatively new recruit to the world of technical authoring, discovered that occasionally being kept in the dark can be annoying. In honour of this momentous occasion, I offer to you for your delectation my own top ten ways to annoy a Technical Author.
- Get them to produce a documentation product estimate based on functional specification with statements that contain “It is likely that this may change”.
- Add, remove or change the fields on a dialog after it has been documented and not tell you.
- Remove a large area of functionality you have spent weeks documenting on the day of the deadline for the final product build.
- Write a functional specification that mirrors a conscious brain dump of information with little or no logical structure.
- Ask them to make a “minor” change to a document whilst singularly failing to realise the implications of such an action.
- Ask them to produce an online version of a paper document and give them the paper document.
- Complain that there is no documentation without even looking.
- Ask them to produce a document, then never approve it and ask for the same thing a few months later.
- Give them a typing test during their job interview! After all that’s all they really need to know.
- Tell them Microsoft Word should be plenty to produce user documentation.
Welcome to the world of technical authoring.
Note: My thanks to Laurin Marden (follow her on twitter – @lmardennh) for the inspiration, and some of the content, for this post.
Linking to topic bookmarks in a merged project set-up 10th November 2009 (Tuesday)
Posted by Colum McAndrew in Adobe, RoboHelp.Tags: .CHM file, Bookmarks, build tags, CHMs, Consitional build tags, Microsoft HTML Help, Single Source Layouts, WebHelp, WebHelp Pro
add a comment
The team of authors working on the complete rewrite of one of our product suites are nearing completion of a year’s worth of effort. We have a merged project set-up, outputting to both CHM files and WebHelp Pro output, with 12 child projects inside the parent.
One of the final tasks is adding inter project links from topics inside a child project to topics inside other child projects. This is complicated somewhat by having to produce the two distinct outputs, meaning that the syntax for these links is different depending on whether you are pointing to a CHM file or not. This is easily solved however through the use of two conditional build tags and a conditional build tag expression in each of the Single Source Layouts to exclude the relevant tag.
All was going well until in some instances we wanted to link to a topic bookmark. This produced another issue as the bookmark did not appear in the dialog when linking either to a file or a CHM file topic. For example:
We managed to get around this by selecting the relevant topic or HTM file (depending on the output being produced) and manually adding the bookmark after it. For example to link to the “Add” bookmark on the Dictionary_Terms topic the link would be:
- Sysadmin.chm::/dictionary_terms.htm#add (for the CHM file link)
- file://mergedProjects/SystemAdmin/ dictionary_terms.htm#add (for the WebHelp file link)
Tip:
In order to help ensure you enter the bookmark correctly, cut and paste the bookmark names as you add them to a Notepad file. Then when you add manually add them to your link, you do not have to manually type them out.
A default Single Source Layout. What’s the point? 29th October 2009 (Thursday)
Posted by Colum McAndrew in Adobe, RoboHelp, RoboHelp Server.Tags: CHM, CHMs, FlashHelp, FlashHelp Pro, HTML Help, Layouts, Microsoft HTML Help, Single Source Layouts, table of contents, TOC, WebHelp, WebHelp Pro, windows
2 comments
If you have only ever created a new project whilst specifying the output layout to be produced in the process, this is a question you may have never had to ask. However if you’ve had to change the output layout being produced from your project (e.g. for Microsoft HTML Help to WebHelp) or you output two or more different layouts, you will almost definitely have had to address this.
On the face of it, your default single source layout allows you generate your chosen output by clicking a single toolbar icon. This is all very handy if you don’t have the Single Source Layouts pod displayed at the time but it is so much more than that. It also controls your project windows and table of contents properties.
Take start with a look at your humble window. Isn’t it just a container in which you display your help? Unfortunately it isn’t quite as simple as that as the default single source layout at the time the window was created determines what window characteristics can be changed. The reason for this is that web based output (e.g. WebHelp) uses a browser to display the help contents. With a CHM file you have much more control over the window used to display the help because it is a single compiled locally installed file.
As well as this, the window properties available differ. As web or flash based output requires a skin to control much of the look and feel of your output, the window definition needs minimal supervision. For example the skin controls colours, buttons, fonts, etc., whilst the window controls placement, default tab and properties when viewed from a context sensitive help API. With Microsoft HTML Help (.CHM) output it is the window that controls the buttons that are displayed as well as the look of the tri-pane container.
As for your Table of Contents, the default single source layout controls the properties of your books and pages. If Microsoft HTML Help is your default layout you can assign different book and page icons in the Advanced tab via the “Image” field. This is not available with other layouts.
Hopefully now you understand that your default single source layout controls so much more than the default output produced. So if you ever face a situation where you can’t change the properties of your Table of Contents or help window, check your default single source layout setting. Changing your default is as easy as right clicking on the single source layout (in the Single Source Layout pod in RoboHelp 7 or later) and clicking “Set as Primary Layout”.
Note:
If you are publishing WebHelp Pro or FlashHelp Pro output, the default single source layout also controls the use of the RoboHelp Server pod (available in RoboHelp 8). If the default single source layout is anything other than WebHelp Pro or FlashHelp Pro, the Setup button in this pod will not be available for use.
Importing a PDF into a RoboHelp Project 28th October 2009 (Wednesday)
Posted by Colum McAndrew in Acrobat Professional, Adobe, RoboHelp.Tags: Importing, Optimizer, PDFs, Print Drivers
add a comment
Some users have had issues importing a PDF into a RoboHelp project. This is normally where a PDF created in an old version of Adobe Acrobat (e.g. Acrobat 6) is being imported into a RoboHelp 8 project, or a PDF created in the latest version of Adobe Acrobat (version 9) is imported into an older version of RoboHelp (e.g. RoboHelp X5). Normally the user gets an error message such as “Unsupported or corrupted file” yet the PDF opens perfectly OK in Adobe Acrobat. What gives?
This is one of those occasions where the error message is slightly misleading. The issue with it is that it is ones natural reaction to focus on the word “corrupted” with all the connotations that it brings. However the word “unsupported” gives the real key to the problem. In the above scenarios you have a mismatch between the product versions. As Acrobat 9 was released after RoboHelp X5 and RoboHelp 8 was released after Acrobat 6 I guess you have to suspect problems with backwards compatibility. It’s a bit like installing your old DOS Asteroids game on Windows 7 and expecting it to run flawlessly!
So how do you get around this conundrum? There are a couple of workarounds:
- If you are importing your PDF into a RoboHelp 8 project, get hold of an earlier version of Adobe Acrobat from which to create your PDF. Another option is to use one of the many free PDF convertor tools to be found on the internet.
- If you are importing a PDF created in a newer version of Acrobat into a older version of RoboHelp (e.g. RoboHelp x5) you have a couple of options:
- The first is to print the PDF to the Adobe Printer print driver, saving the file as a PDF. Reports have indicated that the PDF imports into RoboHelp with no issues.
- If you have access to Acrobat Professional, use the Optimizer function saving the file as an earlier PDF version. Creating a PDF in this way takes slightly longer but also works well. Note however that this method removes and invalidates any digital signatures.
Forgotten User Passwords on RoboHelp Server 8 26th October 2009 (Monday)
Posted by Colum McAndrew in Adobe, RoboHelp Server.Tags: Database, Passwords, ru_UserID, Tables, TRobouser table, Users
add a comment
A few months ago I saw a user wanting to know if they could retrieve the password issued to a user accessing an area on the RoboHelp Server 8. This is a reasonable question considering that the UI of the Web Administrator does not allow you to edit a user once it has been added. So if you have created a user, and emailed them a password but not recorded it anywhere, there appears to be no way of finding out what that password was should it get forgotten or lost. What is more, deleting the user and re-adding them is not allowed as the RoboHelp Server database still has a record of it.
I thought there probably was a way to rediscover a user password, if not in the UI then under the hood so I emailed Tulika Garg at Adobe to find out where. The response back said that there was in fact no provision for finding out a forgotten password. Once it was lost, it was lost for good. However as a workaround, you can edit the RoboHelp Server database as follows:
- Open the RoboHelp Server database.
- Find the TRobouser table.
- Look for the table row that has the ru_UserID value of the user whose password is forgotten.
The result of this is that you are able to add the user again via the Web Administrator and prompt you for a new password. Of course it goes without saying that taking a backup of the database is a precursor to the above procedure. Better still create a text file somewhere where you can record the userids and their passwords.
RoboHelp Server 8 Area Directories 22nd October 2009 (Thursday)
Posted by Colum McAndrew in RoboHelp Server.Tags: Areas, Directories, Protected, Unprotected
1 comment so far
I happened to be looking around our RoboHelp Server box the other day and decided it would be useful if there was a shortcut on the desktop to the location of our help output when it is published. The trouble was, where was it placed?
The properties of the WebHelp Pro single source layout gave me some clue. After all it provided the path to the server and the area to which we were publishing. With that information it shouldn’t be that difficult. I started digging around the C:\ drive and discovered the following directory:
C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\server
Now I was on to something, especially as I also discovered that there was a sub-directory to it that mirrored one of the areas we had published to. Whoopee! But just as I was getting carried away with excitement (yes I know it is sad to get so excited over such things) what should I discover but the following directory:
C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\secure_server
Oh! Hang on a minute. What is this? It too has sub-directories that mirror areas to which we have published. What is more some areas appeared in the secure_server whilst others appeared in the server directory. None appeared in both. What was going on?
Then all of a sudden I had a hunch. Could the difference be whether an area is protected in the Areas dialog of the Web Administrator? I created a new area ensuring I ticked the “Protected” option. Having published some output to it, lo and behold it appeared in the secure_server directory. If I made the area unprotected and published the output, it appeared in the server directory. I had cracked where to point my desktop shortcut.
In summary, output is placed in the following server directory:
- Protected: C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\ secure_server\areaname
- Unprotected: C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\server\areaname
