File updates are to be performed by the authoring individual. The information as to the author and the last revision date can be found on the bottom right-hand corner of each subject. When a file needs to be revised, send a copy of the file to the author or designated individual. That person should perform the changes required. When the changes are complete, you will receive an email informing you of the location to find the file for inclusion.
Updating the manual is conditional depending on what changes were made. First and foremost, the file name has to match the original name. If text only changes were done then the editor needs only to copy that new file over the old one where it resides in RoboHelp. If graphics of any sort or hyperlinks were added or deleted then the file will have to be imported into RoboHelp and another compilation will have to be performed.
It is always a good idea to test file changes once the file is in place. Make sure graphics are represented correctly and that all hyperlinks are functioning. Ensure that any Keyword in the document also appear in the Keyword list.
A copy of the entire manual needs to be maintained external of RoboHelp. The editor should make an archive of the entire directory. Updates need to be uploaded to the server as well as outlined in the RoboHelp documentation. The simplest method to do this is to perform a final compilation. Go to the appropriate directory on the server and delete all the files contained therein. Then you can return to the local directory / folder and select all, copy, then paste to the server. This ensures that outdated files are removed and an exact duplicate in on the server. ALWAYS test the new version for functionality not only from your computer, but from other computers and operating systems to test compatibility.
In order to make some sense from the many files that comprise this manual a naming convention has been implemented. This naming convention is based on where the file resides within the structure of the book. This method is used to lend flexibility to file management. Typically conventional file names, i.e., whatever_it_maybe.htm, can be limiting. Due to the nature of the subject matter, we run into situations of closely related file names but with totally unrelated content. With the way online directories are structured one can quickly find themselves lost when trying to retrieve a file for maintenance of the document or manual or even just to add a file to the manual.
For the GBT Operations Manual a mnemonic naming convention is used. Each major division within the manual is given a 2 to 4 letter mnemonic designator. A chapter will have a designator, then a subject within that chapter, and then topics within the subjects. Each designator within the file name is separated by an underscore "_" and the last part of the name before the file extension can be a descriptive term for the file as opposed to a designator. For example:
Manual Table of Contents Sample
In the above sample the filename associated with the indicated topic is od_iflo_rcvr_fe_char.htm This file name is appended to the text of the file in the bottom right corner so that files can be quickly recognized for editing once they have been incorporated into the manual.
Graphics will be submitted by the author as inline files. The names of these files will reflect the descriptive names of the host files. Refer to the example in the previous section. If there were a picture within the indicated document it could be named rcvr_fe_char_fig1.gif. If there were more than one graphic file then the number within the file name is incremented for each successive picture retaining all other characters of the first. i.e.;
rcvr_fe_char_fig1.gif
rcvr_fe_char_fig2.gif
rcvr_fe_char_fig3.gif
As these pictures are imported the alignment may be altered and thus these pictures will have to be reviewed for appropriate properties. All graphics files will be submitted as either .jpg or .gif files and should be of relatively small size. If a picture has to be included that is overly large, a thumbnail can be displayed in the document and clicked for the enlarged view, however, this is being discouraged.
As mentioned above, an archive of the entire manual directory needs to be saved independent of RoboHelp. This is to protect the manual from catastrophic events related to RoboHelp or the server. Again, to simplify the efforts required of the editor, the current date is utilized for versions of the manual with the option to change to a "Version Number" later when development slows.
For now the manual on the local machine, where the source files reside, are in a folder named "opsman_mm_dd_yy". When these files are changed, the date in the folder name is incremented as well. When the online copy of the files are updated the files on the server are deleted from the online folder and the new version is copied and pasted from the local computer into the online folder. The online folder does NOT get it's name updated. This will maintain integrity with the hyperlinks from referring web pages.
The date located on the opening page on the manual will need to be updated as well.
Keywords for the index are to be taken from major subjects and topics. These are organized in the keyword list in much the same manner as the files are organized in the book. If needed, words within topics can be added.
Files submitted for inclusion should have correct tags in place for the various headings as described in the Writer's Guide. Upon implementing the file the editor needs only to link the file or files to the external style sheet within RoboHELP to impart the styles needed for the new documents to conform to those already used within the manual. This style sheet is named opsman.css.
Prepared by: Eric Knapp, GBT Operator
Last revision: 12 JAN 2001