The "My Documents" folder. The scourge of Technical Authors.
The My Documents folder prevalent in the Windows OS is a great idea. Its purpose is to be the default repository for storing all those files that you need on a regular basis. What is more, the OS automatically directs you by default to the folder from just about everywhere. Open up Windows Explorer or save a file in Microsoft Office and the default location is your My Documents folder.
So far that’s OK. Things started to get a little sticky when application developers decided it would be a good idea to create sub-directories inside your My Documents directory to house all the files you create using it. RoboHelp (from version 7), Paint Shop Pro, and FAR are just three applications I use frequently that by default insist on creating these folders. So, is this a problem?
Well, RoboHelp is well known in authoring circles to have issues when run over a network because of the MS Access database at the core of each project. In a corporate environment you are bound to have networks. Such networks are easily identifiable by their network drive. See a drive letter of W:\ or T:\ and you know what you are dealing with. But what about your My Documents folder. That’s local, right? Chances are you are wrong! It is common for Network Administrators to map your My Documents folder and your desktop to the network to enable you to logon at any networked PC and to access your data. Rick Stone describes this very well on one of his RoboWizard Monthly Scrys.
But networks are only one half of the problem. Occasionally the RoboHelp forums see posts where users have issues with compiling, generating output, or some other problem. There appears to be no logical reason for the error. That is until you look at the error thrown out. The file path for the project normally looks something like this:
C:\Documents and Settings\Username\My Documents\My RoboHelp Projects\Some Very Long RoboHelp Project Name\!SSL!\Printed Documentation\!chm_tmp_folder_0\A Very Long RoboHelp Project Name.hhp
Wow! Including the spaces that is nearly 190 characters. Best practice suggests the following:
- Keep directory names and filenames as short as possible whilst keeping them meaningful. This may be easier for people like me who remember the days when Windows 3.1 limited you to eight character file and folder names. Boy that made you think long and hard about naming conventions.
- With RoboHelp, or indeed any application that defaults to adding files to your My Documents folder, create a folder off your C: drive. I use a folder with the path C:\RHSource with subfolders for each of my projects. You can always copy the folder to the network later.
- Change the output folder of your Single Source Layout to a folder somewhere other than the default \!SSL!\Single Source Layout Name folder. For example create a folder called Output inside your project directory.
Follow these tips and you end up with something like the path below. A significant improvement and you won’t loose any sleep or hair as a result as the long path name issue will be a thing of the past.
C:\RHSource\Project Name\Output\!chm_tmp_folder_0\Project Name.hhp
Customisable To Do List Items to meet your workflow
Your Project Settings and the Manage To Do List dialog
If proof were needed that Adobe were listening to their users, you need look no further than the Topic Properties dialog in RoboHelp 8. One of the major problems with tracking documentation projects was the list of to do items that could be applied to a topic. The list was static and limited. With the arrival of RoboHelp 8, all that has changed.
The statuses are held inside the project’s .xpj file in the <TODOLIST> section. As such you can copy the statuses between projects if you feel comfortable with editing it. Just close your project, open the .xpj file up in Notepad and copy the <TODOLIST> section. Now paste the text into the other project’s .xpj file. Needless to say, the usual precautions apply about making backups before doing anything.
Podmania
The arrival of RoboHelp 7 saw a major change to the user interface. Out went the static dual-pane interface and in came a multi-dimensional, fully customisable interface that could meet the exacting standards of users. Pods made an appearance with the various project elements grouped logically together. This meant users could display only the project elements they needed at a particular time, thereby eliminating clutter, yet also have them available easily whenever required.
RoboHelp comes with an “out of the box” environment with pods arranged in a default pod environment. From here you can position pods around the screen, pin them to a margin or close them completely. Whilst the default environment gives new users a pretty good interface to work from, more seasoned users will soon feel the need to change it. This is very easily done with some 17 available pods in RoboHelp 8. The trouble is, things are almost too easy to customise. Before long, you can easily find yourself with pods hidden or closed and unable to find them again if you are not careful.
Thankfully, Adobe have thought about this and have added two methods of helping you should you get into trouble:
- Custom environments. These allow you to customise your environment and save it to an .rhs file which can later be loaded (see below). This is be particularly useful for projects with different requirements as you could save two or more environments that can be loaded for the particular project.
- File > Environment menu item. The RoboHelp forums often have posts from users unable to find a particular pod. The File > Environment > Load Default Environment menu item restores the “out of the box” environment. Similarly, if you have saved a custom environment, the File > Environment > Load Environment menu item can be used to locate the required .rhs file.
RoboHelp 8 and the .CPD file
You often see mention of the projectname.cpd file on the RoboHelp forums. This little beastie is the cache for your project held in an Access Database and is essential for your project to function. Yet occasionally it can cause you all sorts of fun and games with users accusing it of dramatically increasing in size or some other such misdemeanour. Personally I’ve only very rarely had any problems with it but others have been less lucky.
Under normal circumstances, the solution to problems with the file is to delete it. If you prefer to be safer, rename the projectname.cpd file (e.g. projectnameold.cpd file) rather than deleting it just in case. You can always delete it later. This may seem rather drastic to an essential project file but it is recreated when you open a project if it doesn’t exist. By recreating it, you hopefully eradicate any problems that existed with it.
With the release of RoboHelp 8, maybe problems with this file will largely become a thing of the past. Tucked away in the General tab of the Options dialog is an tick box called Clear project cache (.cpd) before opening any project. With this option checked, the projectname.cpd file is automatically deleted and recreated whenever you open any project. This will hopefully stop any problems with the projectname.cpd file before they start.
Update: For an fuller explanation of the CPD file, click here.
