To better support Green Bank operations as well as the observing community, the GBT Operations Manual is designed to exist in both a web page format and as a printed document. Reasons for this are simple. The web version allows off-site individuals planning their future use of the GBT, easy access to pertinent information concerning telescope systems and the procedures used by operations to run them. All this by simply going to an NRAO web site. As for the benefits of a printed manual, these should be obvious to any veteran of telescope operations. To achieve this kind of flexibility, the software program RoboHELP® was adopted.
RoboHELP® is a web authoring tool used to generate help menus in an HTML format. To reduce the effort needed to build and maintain our manual, all documents going into RoboHELP® must be in an HTML format before their addition. Not everyone is familiar with generating a document in HTML however, or should be expected to learn this format in order to contribute to our manual. To help alleviate this problem, we have adopted additional software and developed this guide. This guide will detail the software programs you can use to prepare documents for inclusion into our web based manual. It will also assist you prepare your documents in a way compatible with the requirements of RoboHELP®, from drafting your document in a suitable format and converting it to HTML if necessary, to getting it to us and into the manual correctly and efficiently. In the sections that follow, specific guidance is provided to assist with these tasks.
First off, in order to generate an operations manual that is functional, maintainable, and good looking in appearance, a certain amount of standardization is necessary. RoboHELP® is capable of applying a consistent style throughout the manual by way of cascading style sheets. It can't however, accommodate for the variations in style an author may apply to the content and arrangement of their specific document. To overcome this problem, reduce compatibility errors, and reduce the need for the editor to manually arrange and manipulate your submissions for the manual, the following basic guidelines have been established.
Type:
Style:
Size: Chapter Titles (?), Subject Titles (?), Topics, Subtopics, and all paragraph text (?)
Color
Effects:
Symbols: All commonly used symbols can be used.
Character Spacing: Normal
Line Spacing: Single
Margins: Top/Bottom: ; Left/Right:
Page Orientation: Portrait
Width/Height: (8.5x11)
Border style, color, and width:
Table Shading:
Table Alignment: Centered
Formats accepted: Only JPEG and GIF formats should be used as these are what HTML require. If you're using MS FrontPage® to generate your document however, additional formats can be used as this program will convert them to either JPEG or GIF for you.
Size: As small as possible to keep file sizes down and web page loading times reasonable. The use of "thumbnails" will be at the discretion of the operations manual editor. Keep in mind that the printed version of the manual must fit on standard 8.5 x 11 paper.
Placement: Inline with text. Do not place at the end of your document as an attachment.
Caption Lines: Contents at authors discretion. Caption should be placed one line below and centered with the image.
File Names: Your pictures must have names that not only identify them to you, but will also identify where they belong in your document. This information is important to the editor as the program RoboHELP manages all image files in a folder separate from your HTML text. Please use the following format:
descriptive file name_part of docuement.(applicable file extension)
An example of this format would be: ReceiverX_Fig1.gif
In this example, "ReceiverX" is a description assigned by an author to identify the image as relating to receivers, in particular an x-band receiver. The "_Fig1" identifies where the file fits into the overall document. In this case it's Figure 1 (part of the caption line). For multiple images, simply adding a different number can be used. This will ensure your images are properly located within your document and help the editor should later changes be made.
Using a Point of Contact Line. To help identify a documents originator and show its date prepared, a point of contact line will be included at the bottom left corner of each document file. This information will help the editor and readers should changes or clarification in the document become necessary. Please use the following format: Name/Organization/Date Last Modified/File Name (See paragraph 2.5 for specifics on file naming.)
File Naming Convention. To help the editor correctly arrange your document into the manual, files submitted need to have a standardized and easily identified naming scheme. Please use the following format:
descriptive file name_part of docuement.(applicable file extension)
An example of this format would be: ReceiverX_intro.htm
In this example, "ReceiverX" is a description assigned by an author to identify the document as relating to receivers, in particular an x-band receiver. The "_intro" part of the file name identifies where the file fits into the overall document. In this case it's an introduction. For small, single topic or subject document files, this extended part of the file name is unnecessary. For long documents however, adding a number may be advantages. An example here would be a set of files named "ReceiversX_1", "ReceiversX_2", and "ReceiversX_3" where the added number shows the order the files are to be arranged by the editor.
Glossary Terms. If your document contains terms you want included in the manuals glossary, then a list of these terms, along with a brief description for each, should be included as a separate file with your document. The editor will add the words and descriptions to the glossary and create the necessary hyperlinks for the web based manual.
Saving Documents by Sections/Size. As noted before, the Operations Manual will exist in both a printed and on-line web format. In order to keep the web version manageable (with web pages of a reasonable length to reduce the need for excessive scrolling within a window), your document should be organized to keep each section or topic area to two printed pages or less. Topics greater than two pages in length should be split at a convenient point. To explain this further, consider an example using the following chapter about GBT backend instruments:
Backend Instruments (Chapter) (Generalized text concerning the purpose/content of this chapter)
Spectrometer (Subject) (Includes text introducing this instrument while leading into additional topics)
Major Components (Topic) (A brief discussion of this topic with a lead into its two subtopics)
Sampler Rack (SubTopic 1) (Specific text, tables, or graphics concerning this topic)
Correlator Rack (SubTopic 2) (Same as above)
In this example, let's say the text from the chapter beginning through the topic Major Components takes up about two pages. At this point the document should be saved and a specific file name (see paragraph 2.5) given. Subtopic 1 takes up about two pages, hence it should be saved as a separate file. Subtopic 2 on the other hand consists of about four pages of material. In this case, this topic should be split near the two page point and the topic saved and named as separate files. It should be noted that this "breaking up" of your document will be transparent when later assembled into the operations manual with RoboHELP®. By following this procedure, web pages will be kept to a reasonable length and links between topic areas will be easier managed. Also, should updates to your document's information be required, only the specific file needing changes will need to be modified and submitted, saving both you and the manuals editor time and effort.
Table of Contents. A simple table of contents should be sent with your document as a separate file or noted in an email. The table of contents will be used by the editor as a topics list to aid in making hyperlinks within RoboHELP® (needed for easier navigation within the web based version of the manual). It will also ensure your document is organized into the manual correctly. A table of contents is not required for single topic pages or documents like checklists.
Formats We Can Accommodate. As noted in the overview, RoboHELP® works in HTML. For those who can prepare your documents in HTML directly, just follow the guidelines we've established and you'll be on your way. For users of MS FrontPage®, word processing programs like Microsoft Word, or ASCII text editors, we have developed a few procedures to help.
Generating a Document Using MS FrontPage®. The software program MS FrontPage® is our preferred tool for generating a documents for the operations manual. While this program was designed primarily for developing web pages, our use of it is limited to that of a simple editor, capable of generating pages of documentation in an HTML format. The program serves an additional purpose as a filter. In this capacity, we can use it to convert MS Word® and other text file documents to an HTML format. If your file is sent to us in a .doc or .txt file format, this is the tool we will use to convert it to HTML. The program is relatively easy to use and has an editor that looks and functions very much like other word processing programs. To help you get started and assist with format standardization, a predefined page template is available. Specific guidance on using MS FrontPage® follows. For additional information and assistance, please refer to the software's user manual or help menus.
Once MS FrontPage® is running, click File then New and select Page. When the menu pops up, double click on the template labeled "Ops Manual". The page will now load. (Note: This template can be provided upon request. A master copy is located in the directory: //halebopp/gbt ops/templates).
Follow the guidance on the template, replacing the preformatted text areas with your own. Duplicate sections as necessary using standard "copy and paste" functions. Delete any areas not needed. Using this process should save you effort in manipulating fonts and dealing with other formatting concerns.
If tables are used, follow the rules noted in paragraphs 2.2. Tables should be placed in line with your text. Do not incorporate them as attachments as this will make insertion of them and your document into RoboHelp® much more difficult. To create a table:
In Page view, click Draw Table on the Table menu. FrontPage opens the Tables toolbar with Draw Table selected.
On your page, draw the outside border of the table by dragging from the upper-left corner to the lower-right corner of the table. To make cells, draw vertical and horizontal lines within the table. To remove any lines you do not want, click Eraser on the Tables toolbar, drag across the unwanted line, and then when the line turns red, release the mouse button.
When you have finished drawing the table, click Draw Table on the Tables toolbar so that the button is no longer selected.
If a graphic or picture file is used, follow the rules noted in paragraph 2.3. These objects should be placed in line with your text for the same reason noted for tables. You can add the picture from your local file system. GIF (standard) or JPEG (standard) formats should be used. Formats such as BMP (Windows and OS/2), TIFF, TGA, RAS, EPS, PCX, PNG, PCD (Kodak Photo CD), and WMF can be imported into MS FrontPage® where they will be automatically converted to either GIF or JPEG depending on the number of distinct colors used. To insert a graphic or picture file:
Position the curser where you want to insert a picture then click the Insert Picture icon followed by clicking File.
Go to the directory where your picture is located, select it then click the OK button. The picture will then be inserted.
Name your file using the file naming convention noted in paragraph 2.5
Submit your file using the guidance in paragraph 5.
If you don't have MS FrontPage®, MS Word® or a similar text editor is your next best choice. A document created in MS Word® can be saved as an HTML file, for reasons stated later however, we strongly recommend against this. To convert your document to HTML, MS FrontPage® should be used. The following steps are based on using MS Word® though they may be adjusted to accommodate other brands of word processing software.
To start a new document file using our predefined template:
Once MS Word® is running, click File then New. When the menu pops up, double click on the template labeled "Ops Manual". The page will now load. (Note: This template can be provided upon request. A master copy is located in the directory: //halebopp/gbt ops/templates).
Follow the guidance on the template, replacing the preformatted text areas with your own. Duplicate sections as necessary using standard "copy and paste" functions. Delete any areas not needed. Using this process should save you effort in manipulating fonts and dealing with other formatting concerns.
If tables are used, follow the formatting rules noted in paragraphs 2.2. Tables should be placed in line with your text. Do not incorporate them as attachments as this will make insertion of them and your document into RoboHELP® much more difficult. Additional information about inserting tables into your document are outlined in MS Word® help menus. To create a table:
Go to the Table menu and click Draw Table. MS Word® opens the Tables toolbar with Draw Table selected.
On your page, draw the outside border of the table by dragging from the upper-left corner to the lower-right corner of the table. To make cells, draw vertical and horizontal lines within the table. To remove any lines you do not want, click Eraser on the Tables toolbar, drag across the unwanted line, and then when the line turns red, release the mouse button.
When you have finished drawing the table, click Draw Table on the Tables toolbar so that the button is no longer selected.
If a graphic or picture file is used, follow the formatting rules noted in paragraph 2.3. These objects should be placed in line with your text for the same reason noted for tables. Pictures can be added from your local file system with most of the popular formats accepted. (Note: If the picture is not in GIF or JPEG format, pictures that use 256 or fewer distinct colors will be converted to GIF, and all other pictures will be converted to a JPEG format when this document is brought into MS FrontPage for conversion to HTML). Additional information about inserting graphics into your document are outlined in MS Word® help menus. To insert a picture:
Position the curser where you want to insert a picture then click the Insert Picture icon followed by clicking File.
Go to the directory where your picture is located, select it, then click the OK button. The picture will then be inserted.
As noted before, MS Word® can save your files in an HTML format. Unfortunately, this process tends to shift tables and inserted graphics to your pages left margin. Instead of converting the document to HTML in MS Word®, just save and send it to us as a regular document (.doc) file. We will convert it to HTML using MS FrontPage® by simply inserting it into a blank page then saving it as HTML. If you do happen to save your document as an HTML file in MS Word®, please include instructions, separate from your document, advising us of where and how your graphics should be placed.
Additional notes. The drawing tools available in MS Word® should not be used as the resulting objects are not HTML compatible and cannot be imported into MS FrontPage®. If you need to draw something for insertion into your document, we recommend you use a software program that can draw and save the object as a JPEG or GIF file. The object can then be pasted into your document and handled later in HTML.
Name your file using the file naming convention noted in paragraph 2.5
Submit your file using the guidance in paragraph 5.
An ASCII text editor such as MS Notepad can also be used to prepare your document. This however, is the least desired format to use as it is extremely limited in capability. This editor has no provisions for controlling formatting parameters (such as fonts, text size, etc.) or for handling tables or graphics. It should be used only as a last resort! If you should have to use it, please follow our formatting guidelines where possible and feasible within the limitations of the program. Final formatting of your document, prior to its conversion to HTML, will have to be accomplished by the editor or other on-site personnel. Any special instructions concerning the formatting of your document should be provided.
Getting started. Simply open the editor as noted by the software's user manual and prepare your document according to the requirements of this guide.
Name your file using the file naming convention noted in paragraph 2.5
Submit your file using the guidance in paragraph 5.
Initial there are two ways to submit your operations manual files. If the document is small, say a 1-2 page checklist, it can simply be emailed to the editor. The editor will then take your document and enter it into the manual as necessary. For long files, we recommend that you place your document directly into the folder //halebopp/gbt ops/upload. This will eliminate the need for sending emails with large attachments. Both methods should include an email to the editor noting any special concerns or instructions associated with the document. For multiple file documents, the sequence the files are to be arranged must be included.
Updated Files. More often than not, an updated document file will be small since only those sections that have changed will need to be sent. Therefore, we suggest you simply email your updates as noted above. Updated files must have the same name as originals. Minor changes will be incorporated on a periodic basis. If your update consists of major revisions however, please inform the editor. These will be handled promptly as conditions permit.
Prepared by: Dave Rose, GBT Operator
Last Revision: 12/5/00