User Tools

Site Tools


training:docs_style_guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

training:docs_style_guide [2010/07/30 13:02] (current)
charlene created
Line 1: Line 1:
 +
 +Windward System Five Style Guide
 +
 +Table of Contents
 +
 +DOCUMENT OVERVIEW AND PURPOSE 2
 +Correcting common legacy Help errors 2
 +When referring to screen captures 2
 +Use step numbers for instructions and bullets for unordered lists 2
 +When instructions refer to buttons or other screen components 3
 +Improve sentence structure 4
 +Correct the use of Person 4
 +Cut out wordiness and jargon 5
 +Use the present tense 6
 +Use active voice 6
 +Use American spelling 7
 +Apply standard capitalization rules 7
 +Restructuring the Help 10
 +Phase 1 structure 10
 +Strength 10
 +Weakness 10
 +Phase 2 structure 10
 +Changes from phase one 10
 +Using Help cascading style sheets 11
 +Structuring Help topics 12
 +1.0 Window/​Report template 12
 +2.0 Instruction/​Introductory information template 15
 +Windward-specific document conventions 16
 +
 + 
 +DOCUMENT OVERVIEW AND PURPOSE
 +We use the Microsoft Manual of Style as our style guide. The purpose of this document is to inform writers of common legacy documentation errors and giving examples and rules for correcting them. Armed with this information,​ writers can target these specific concerns for improvement during the regular documentation update cycles.
 +
 +This document discusses the strengths and weakness of the more formal phased restructuring of the Help and includes examples of specific format guidelines used. Included at the end of this document are the Windward-specific formats that the documentation group decided to follow as exceptions to the standard.
 +Correcting common legacy Help errors
 +The original Help was written by the individual developers as they finished coding a new feature or function. This approach created a number of legacy issues with inconsistent format, poor grammar, incompleteness and inaccuracy of the documentation. The following sections show specific examples of the legacy issues that need to be addressed along with the applicable guidelines and corrected examples.
 +When referring to screen captures
 +When referring to screen captures avoid using the term ‘pictured’ as in the following example: ​
 +
 +Incorrect: The Settings Tab is pictured in Figure 1, below.
 +
 +Correct: The Settings Tab is shown in Figure 1.
 +
 +Note: When the descriptive text is right above or below the screen capture and it is numbered or labeled, it is redundant the mention ‘below’ or ‘above’. The user sees it right away and it is already labeled for clarity. Graphics in tables or instructions do not need to be labeled or referred to for the same reason.
 +Use step numbers for instructions and bullets for unordered lists
 +When describing processes or procedures it is always clearer to the reader when step numbers are used, especially when there are a number of screen captures added in between. Each step should start with a user action and then detail all reactions to that action such as a window appears or a button/​field becomes available/​editable. ​
 +
 +Use a bulleted list for an unordered series of concepts, items, or options rather than a sequence of events or steps. ​
 +
 +Introduce a numbered or bulleted list with a sentence or fragment ending with a colon. Begin each entry in a bulleted or numbered list with a capital letter.
 +
 +The following is an example (without the screen captures):
 +
 +To create a header ledger account, select the parent header account (if there is one), right-click or press the Account button. A popup menu will appear.
 +
 +New General will create a first level Header Numbers.
 +New Sub General will create a new General Account as a child of the current selected General Account. ​
 +New Detail will create a new Detail Account as a child of the selected General Account.
 +Select New General or New Sub General then the corresponding account type. Assets can only be put under assets etc.
 +
 +Then fill in the description.
 +
 +Next drag and drop the detail ledger or other header ledger numbers under the header ledger you just created.
 +
 +Same example with step numbers (and other revisions):
 +
 +To create a General (Header) Account complete the following steps:
 +
 +1) Select the parent header account (if there is one).
 +
 +2) Right-click or click. The popup menu shows the following choices:
 +
 +• Menu selections:
 +• New General - creates a first level General (Header) Account. ​
 +• New Sub General - creates a new second level General (Header) Account under the current selected first level General (Header) Account. ​
 +• New Detail - creates a new Detail Account under the selected General (Header) Account.
 +
 +3) Select New General or New Sub General with the corresponding G/L account type e.g. Assets, Liabilities,​ Expenses, etc.
 +
 +4) Enter the account description.
 +
 +5) Drag and drop a Detail Account or other General (Header) Account under the General (Header) Account you just created.
 +When instructions refer to buttons or other screen components
 +When giving instructions to click on a button, refer to the button name only. It is redundant to use the word ‘button’ as in the following example:
 +
 +Incorrect: Click the [Add Item] button
 +
 +Correct: Click [Add Item] 
 +
 +The button name should always be enclosed in square brackets, the font should be bold. Note that if a shortcut is present, the shortcut letter does NOT need to be underlined in the documentation because underlining is extra work for a writer with little value to the end user. The help file discusses generically that an underlined letter is the shortcut key.  In the example above the shortcut is the [Alt-A] on the keyboard.
 +
 +The Microsoft Manual of Style has a section devoted to what to call items on a screen, whether a web-interface or a software GUI. It answers questions like is this a window or a dialog box, a radio button or an option button. There is an alphabetical listing of components that includes examples of the wording you use in instructions for that component type. Please refer to it to ensure the language used is consistent with an international standard that can be easily translated to other languages.
 +Improve sentence structure
 +A sentence is defined as a grammatically self-contained unit of speech or a complete thought. Most sentences include a subject and a verb.
 +Avoid using sentences that rely heavily on implied words. Implied words create localization difficulties.
 +Use an initial capital and ending punctuation for all sentences.
 + Purpose or Intent Use declarative sentences to make statements of fact, opinion, and explanation. These sentences usually follow the subject-verb word order. ​
 +
 + • The color coding shows that the maximum is exceeded.
 + Use imperative sentences to give instructions or commands. Imperative sentences usually begin with a verb. The subject you is generally understood. ​
 +
 + • Click New to create a new employee.
 + Avoid questions. Use interrogative sentences only if you cannot rewrite the sentence. ​
 +
 + Do not use exclamatory sentences (sentences that make strong assertions or surprising observations and end with an exclamation point). ​
 +
 + Length and Readability Avoid using complex sentence structures. They sound pretentious and are hard to read. Complicated ideas do not need complicated language.
 + Aim for simplicity and clarity in your writing. Each word in every sentence must help communicate your ideas effectively.
 + Keep the structure of a sentence simple by:
 +1) keeping the subject as close as possible to the verb
 +2) keeping the modifiers as close as possible to the words they modify
 +3) using conjunctions and transitions to show progress, sequence, connection, and contrast
 +Correct the use of Person
 +Person in English consists of:
 +• first person (I, we) who is the speaker or writer
 +• second person (you) who is the person spoken or written to
 +third person (he, she, it, they, student, customer, user) who is the person or thing spoken or written of 
 +Do not shift person within a sentence or a passage unless the meaning requires a shift.
 + First Person Use first person (I, we) only in some marketing documents or in troubleshooting sections. Use we recommend or we suggest to encourage the user to take some action, such as sending in a registration card; the first person construction is friendlier than the passive it is recommended. ​
 + Second Person Use the second person (you) in most printed and online documentation. Using the second person focuses the discussion on the user, involves the user in the action, and makes it easier to avoid the passive voice. ​
 +In imperative sentences (commands such as Click the New button), the subject is often implied and omitted; if it is, assume that the subject is you or the indefinite pronouns anybody, somebody, or everybody.
 +In procedure steps, omit the you, and use imperative sentences wherever possible.
 +In explanatory,​ informational,​ or reference material, limit the use of you in user’s guides and release notes; you can be used in other types of documents, provided it does not make a sentence too wordy. ​
 + Third Person Do not refer to the reader in the third person, for example, do not refer to the user.
 +                Correct
 +
 +
 +Incorrect On the File menu, click Open.
 +We recommend that you perform daily backups.
 +You can generate a variety of reports in System Five.
 +
 +The user can generate a variety of reports in System Five.
 +Cut out wordiness and jargon
 +Basic Rule of thumb: Use the least number of words possible to convey the meaning clearly and succinctly. Keep foreign language translation in mind where the rates are often charged per word (.15 per word is considered competitive in Montreal for French translation). ​
 +Computer documentation users want to find answers quickly and to get on with their tasks. The goal is to minimize the amount of time spent looking for information and the volume of information needed to accomplish a task.
 +• Keep sentences short and syntax simple. Use short familiar words. Avoid redundant words.
 +• If a choice exists, describe the advantages and disadvantages of the alternatives.
 +• Avoid using obvious phrases, such as in your report, when discussing reports.
 +• Avoid overusing the product name.
 +• Avoid placing unnecessary information between steps in a procedure. ​
 +• Do not document what the audience already knows, such as standard Windows functionality or features common to all Windows software, such as opening a file.
 +Remove all unnecessary words and phrases. Always ask yourself, “What words can I remove from the text without changing the meaning or sacrificing clarity?”
 +• Aim for sentences that:
 +• are clear and direct
 +• have an average length of 10 words
 +• have a maximum length of 20 words
 +• incorporate a variety of kinds and lengths of words
 +Use the present tense
 +The present tense should be used when describing a procedure or process, not future or conditional. Mostly you need to delete the word ‘will and add an ‘s’ to the ensuing verb.
 +
 +Avoid using the past and future tenses as well as the conditional tenses would, could, should or might. Use future tense only when present tense would be confusing.
 +
 +Do not mix tenses within a sentence.
 +
 +Example 1:
 +The Scanpal should beep a couple of times. A window should open up showing the data that is imported. This should disappear after a few seconds. The Scanpal screen will show Sending ..., then clear, and eventually "​Memory Empty" once the data has been successfully uploaded to the computer.
 +
 +Revised:
 +The Scanpal beeps several times. A window then opens showing the data that is imported. It disappears after a few seconds. The Scanpal screen then shows Sending ..., then Clear, and eventually "​Memory Empty" once the data is successfully uploaded to the computer.
 +
 +Example 2: 
 +This will update the stock quantities to the value entered.
 +
 +Revised:
 +This updates the stock quantities to the value entered.
 +Use active voice
 +Use the active voice wherever possible, including in table column headings that list user actions. ​
 +In the active voice, the subject is the doer of the action. An active verb tells who or what is performing the action of the sentence. ​
 +In the passive voice, the subject is the receiver of the action.
 +The active voice is more forceful and clear than the passive voice.
 + Active
 +
 +
 +Passive • Writers sometimes make grammatical errors.
 +• You can divide your document into sections.
 +1) Grammatical mistakes are sometimes made by writers.
 +2) Your document can be divided into sections.
 + When to Use Passive Voice Use the passive voice:
 +4) when the active construction is wordy or awkward
 +5) when the subject is unknown or is not the focus of the sentence
 +6) when you write error messages (since the users are the subject, they might feel blamed for the error if you use the active voice)
 +Use American spelling
 +Use American spelling as opposed to British (or Canadian) spelling. Canadians, Britons, and Australians are more accustomed to and tolerant of multiple spellings of words than Americans.
 +Ensure that your spell checker is set to use the U.S. English dictionary.
 +
 + Correct color,​ labor, favor, center, behavior, check
 +
 + Incorrect colour,​ labour, favour, centre, behaviour, cheque
 +Apply standard capitalization rules
 + Use standard capitalization rules whenever possible. For example, capitalize proper nouns.
 +Avoid overcapitalization. The current practice is toward using lowercase unless there is a specific reason for capitalizing.
 + Do not use all uppercase letters for emphasis.
 +Do not use small caps.
 +Do not capitalize the word, page or step when followed by a number.
 +User Interface Elements Capitalize the names of software user interface elements but not the names of types of UI elements. ​
 +Capitalize the labels of user interface elements even if the interface does not use initial caps. For example, labels on check boxes, edit boxes, options button, and list boxes appear in sentence case in the software user interface; when you refer to these controls in documentation,​ use title case for the name of the label to distinguish it from the surrounding text.
 +Do not capitalize interface elements used generically such as toolbar. ​
 +Correct examples:
 + the Navigator menu
 +the Open toolbar button
 +the Employee drop-down list
 +the Unit dialog box
 +the File menu
 +the Include Phone Numbers checkbox (the checkbox would be labeled Include phone numbers in the user interface)
 +User Input Do not capitalize user input and program output unless they are case sensitive.
 +File and Directory Names Do not capitalize file names, file extensions, or directory names.
 +Keywords links Do not capitalize keywords or links in Online Help unless the keyword or link is case sensitive or a proper noun.
 +Lists and Steps Use sentence case for each item in a list if any list items contain a complete sentence. Otherwise, use lowercase for the first word of each item.
 +Use sentence case for numbered lists or steps.
 +Capitalization and Punctuation Do not capitalize the word following a colon unless the word is a proper noun or the text following the colon is a complete sentence.
 + Do not capitalize the word following a semicolon unless the word is a proper noun.
 +Do not capitalize the word following an em dash unless it is a proper noun, even if the text following the em dash is a complete sentence.
 +Always capitalize the first word of a new sentence. Avoid using a case sensitive lowercase word at the beginning of a sentence.
 +Headings In book and chapter titles, headings, subheadings,​ and table titles, use title case. Specifically,​ capitalize:
 +• the first and last words, regardless of their parts of speech.
 +• all nouns 
 +• all verbs (including is and other forms of be)
 +• adverbs (including than and when)
 +• adjectives (including this and that)
 +• pronouns (including its)
 +• prepositions that are part of a verb phrase
 +• the second word in a compound word if it is a noun our proper adjective or if the words have equal weight
 +• interface and program terms that ordinarily would not be capitalized,​ unless they are case sensitive ​
 +• only the first word of each table column heading
 +Do not capitalize:
 +• articles (such as a, an, the) unless one is the first word
 +• coordinate conjunctions (such as and, but, for, nor, or)
 +• prepositions of four or fewer letters
 +• the word to in an infinitive phrase
 +Measurements Do not use initial caps for measurements,​ unless the measurement is capitalized in common use (640K, 2.5 cm)
 +
 + 
 +Restructuring the Help
 +Phase 1 structure
 +The main purpose of phase one restructuring of the legacy documentation was focused on:
 +
 + Ensuring the user had well-organized,​ consistent, complete screen descriptions with a few examples of how to use the overlying feature. And, using templates to ensure a consistent look and feel. 
 + Adding context-sensitivity and keywords for better user access to information. Adding links between related topics and jumps to take the user back to the main topic overviews to help the user navigate easier.
 + Breaking the source file structure into small chunks (sometimes as small as a window tab) so in future builds information could be included and excluded from the master file depending on what the customer purchased.
 + Using consistent file naming conventions to improve maintainability and document reusable information in invisible topics that are embedded within parent topics. ​
 +Strength
 +It was a good format for collecting and displaying information. The backbone structure allowed for relatively quick access to information and incorporated summarizing and linking of related material. Screens descriptions were comprehensive.
 +Weakness
 +• Counted on the user accessing the Help using the TOC (in a fashion similar to a book) or with F1 (context sensitive). ​ Since this was most often not the case, customers still complained that they could not find access information.
 +• Examples did not encompass all tasks that could be done in a screen or series of screens. The format does not allow for the incorporation of larger scale business knowledge. Examples and example–specific graphics were too high maintenance for the value. The same end could be achieved with well-written task-based instructions.
 +• The structure is very graphics-intensive and again causes maintenance issues. The same end result could be achieved by replacing menu graphics with descriptive text and linking screen descriptions to task-based instructions rather than inserting graphics in the instructions.
 +Phase 2 structure
 +The main purpose of phase two restructuring of both the legacy and phase one documentation was focused on balancing usability with ease of maintenance and to add more business logic with task-based instructions separated from screen descriptions.
 +Changes from phase one
 + To add more access information.
 + To include cascading style sheets to cut down writing time and improve maintainability (reformatting).
 + To modify text and tables to allow for more white space and improve readability.
 + To determine guidelines for chunking information so that global tools can be used and the information is still granular enough to allow for feature-specific Help builds.
 + To correct the grammar and standardize the approach to documenting GUI components to an Internationally accepted guideline.
 +Using Help cascading style sheets
 +{The following instructions detail how and when to use the individual styles. From the Formatting Toolbar, select the correct style from the Style drop-down list prior to typing or inserting a graphic.}
 +
 +Heading 1 - used for the title of a section (such as overview or instructions)
 +
 +Body Text - used for most of the descriptive text. Text wraps without indent.
 +
 +Body Text Indent - used when you want to link a subordinate idea to the previous pararaph without numbers or bullets. Text wraps without additional indent.
 +
 +Heading 2 - used for the title of individual processes within a set of instructions subordinate and related to the previous Heading 1
 +
 +1. Numbered List 1 - used in the first level of numbered statements. Use numbered lists for procedural steps. Write the text, use a hard return between statements. ​ For each step - number the step, click the TAB button on your keyboard, then type the text. Use a hard return between statements. DO NOT use the NUMBERING button on the Toolbar because the numbers get screwed up when you insert graphics. ​ Text wraps with additional indent for the number.
 +
 +• Bullet List 1  - used in the first level of bulleted statements subordinate to the previous paragraph whose style can be Numbered List 1 or Body Text. Write the text and use a hard return between statements. ​ Only use periods if the statement forms a complete sentence. Highlight the items for the bulleted list and then click the BULLET button on the Toolbar. ​ Text wraps with additional indent for bullet.
 +
 +• Bullet List 2  - used in the second level of bulleted statements subordinate to the previous paragraph whose style can be Bullet List 1, Alpha List 1, or Body Text Indent. Write the text and use a hard return between statements. ​ Only use periods if the statement forms a complete sentence. Highlight the items for the bulleted list and then click the BULLET button on the Toolbar. ​ Text wraps with additional indent for bullet.
 +
 +a) Alpha List 1- used in the first level of alpabetized statements subordinate to the previous paragraph whose style can be Numbered List 1 or Body Text. Use alpabetized lists for procedural sub-steps or a list of choices. ​  For each step - letter the step, click the TAB button on your keyboard, then type the text. Text wraps with additional indent for the letter. Use a hard return between statements.
 +
 +List Graphic 1 - chose this style when you insert a graphic in a numbered list. The style indent lines the graphic up with the test.
 +
 +List Graphic 2 - chose this style when you insert a graphic in bulleted list, alpha list or indented paragraph. The style indent lines the graphic up with the test.
 +Structuring Help topics ​
 +There are two templates, one for screen and report descriptions and another for instructions or introductory information.
 +1.0 Window/​Report template
 +If in phase 2 construction how to topics exist separately from screen descriptions,​ then a window/​dialog box description should be an invisible topic and constructed as follows:
 +
 +{Empty line at top}
 +The <​Name>​ Window/Tab Overview
 +{Give a brief overview of what this window enables a user to do. For example:​} ​
 +
 +This window allows a supervisor to define common journal entries required by your business in a template . . .
 +
 +Access
 +{Show the navigation path(s) to the window. For example:}
 +
 +To access the Journal Entry Template window shown in Figure 1, use the following Navigator menu path:
 +General Ledger > Journal Entries > Journal Templates
 +
 +Window Parts Descriptions
 +{Windows and dialog boxes should be described with one topic unless it is a multi-tab window. The Toolbar can be an invisible topic that is embedded into the tab topics. Link to all topics that describe this window. For example:}
 +
 +The Info tab
 +The Cheque tab
 +The Duplicate tab
 +The Transactions tab
 +
 +Related Topics
 +{Include a link to any related 'how to' instructions}
 +
 +Create a journal entry template - supervisors
 +Edit or delete a journal entry template - supervisors
 +
 +The <​name>​ window/​report is shown in Figure 1.
 +
 +{Insert a Picture of the window report Interface}
 +Figure 1: The <​name>​ window/​report
 +
 +{Detail the function and purpose of each of the items on the screen/​tab/​report in a table. Create a table for each major area Toolbar, fields, grid) so you can copy and paste similar characteristics to other topics and save time editing.
 +
 +The function and purpose of each of the components in this tab are explained in detail in Table 1.
 +
 +Item Function and/or Purpose Value
 +Field/​Control name Use the appropriate ​
 +terminology. ​ If you are describing the Columns in a Grid, then use '​Columns'​ and '​Contents',​ for a Toolbar use '​Buttons'​ . Follow the Microsoft Manual of Style for screen terminology.
 +
 +{ Describe the purpose of the field and its relationship to other fields on the screen. State any warnings that may be generated by this field/​control or if it triggers opening of a follow-on dialog box. Insert as many rows as required to provide the required Information for the User.} {Describe the choices allowed in the field. Example: alpha-numeric to a max of 16 characters. ​ Or describe the specific choices in a list and where they come from. 
 +Example, this is a customized list created in the BlaBla screen. Insert as many rows as required to provide the required Information for the User.
 +
 +If the only common features are buttons, this column doesn'​t apply.}
 +Table 1: The Function and Purpose
 +
 +{See an example below:}
 +
 +The buttons on the Toolbar are detailed in Table 1.
 +
 +Button
 + Purpose and/or Function
 +[List] Click to list all unposted journal entries.
 +[Print] Click to open a standard Windows Print dialog box and print the list.
 +[Expand All] Click to expand the entire list and show each transaction on each journal entry.
 +[Collapse All] Click to compress an expanded list into one line per journal entry - default
 +[Post All] Click to post all journal entries in the list.
 +[Delete] Click to delete the highlighted journal entry.
 +[Exit] Click to exit the window.
 +Table 1: The Toolbar buttons
 +
 +You can change the Journal Entry list sort order by clicking on any column header to toggle between ascending and descending order. You can double-click a journal entry to select it and view the details in the Journal Entry Details window (modify if required). The function and purpose of each of the components in the List Journal Entry window grid are explained in detail in Table 2.
 +
 +Item
 + Function and/or Purpose Value
 +Expand Click GLG_List_Selected.bmp to expand the individual journal entry to show each transaction. Click GLG_List_Unselected.bmpto compress an expanded journal entry into one line. By default displays the '​expand'​ symbol. ​
 +Journal Displays each journal entry number (unique system-assigned). Numeric - ascending order
 +Cheque For journal entries that require cheques, this column displays the associated cheque number if you entered one for the record. Numeric - up to 20 characters
 +Book Month Displays the journal entry creation book month for each listed entry. Clicking [List] generates the list of journal entries in date order so this column is usually listed from historical to most recent. Numeric - MM/YYYY ascending order
 +Date Displays the journal entry creation date for each listed entry. Clicking [List] generates the list of unposted journal entries in date order so this column is usually listed from historical to most recent. Numeric - MM/DD/YYYY ascending order
 +Description When expanded, displays the information you typed in the Description field on the Transactions tab (for each transaction) and the Info tab (for the entire journal entry) in the Journal Entry Details window. When collapsed, displays only the information you typed in the Description field on the Info tab. You can use this field to customize the sort order to your business preferences. Alphanumeric
 +Debits When expanded, displays the debit amount for each item on the journal entry and the total for each journal entry. When collapsed, displays only the total debit amount for each journal entry. Numeric ​
 +Credits When expanded, displays the credit amount for each item on the journal entry and the total for each journal entry. When collapsed, displays only the total credit amount for each journal entry. Numeric ​
 +
 +Table 2: The List Journal Entries window components
 + 
 +2.0 Instruction/​Introductory information template
 +A task-based instruction,​ use of a wizard (includes screen grabs as the creens are not documented separately) or miscellaneous introductory information should be constructed as follows:
 +
 +{Empty line at top and for each function such as ADD JOURNAL ENTRY you insert a link to the knowledge base. For example:}
 +Check the Web: Search the Knowledge Base for this Topic.
 +
 +Prerequisites
 +{Enter links to prerequisite processes or setups required before this task can be performed or setups that can affect how this task is performed. . For example:}
 +A template must exist before it can be edited. See creating templates.
 +
 +Edit Journal Templates Overview
 +
 +{Enter a complete description of the how to instruction being documented. You want include what the instruction is, who the user or users are and when they would do this action. State any prerequisite processes and link to the how to for that process. Include the navigation to the first window the user needs for the task. For example:}
 +
 +A supervisor can edit or delete previously created journal entry templates.
 +
 +From the Navigator menu, choose General Ledger> Journal Entries> Journal Templates. The Journal Entry Template window appears. ​
 +
 +To edit a journal entry template
 +{Document all the steps required to do the task including saving and exiting. Each step should start with a user action and include the softare reactions such a a window appearing or a button becoming available. Avoid inserting graphics . . . instead link or jump to the dialog box or window description topic. This keeps the user from scrolling too much and allows them to decide when they need extra information. For example:}
 +
 +1. In the Journal Entry Template window, click the Template Name down-arrow and select the template you want to modify or delete in the list. The [Delete Template] button becomes available.
 +2. To delete the selected template click [Delete Template]. A confirmation dialog box appears asking if you want to delete the template. Click [Yes]. The template name is disappears from the Template Name list and no longer appears in the Navigator menu as an option for new journal entry creation. ​
 +3. To modify the selected template, click [Load]. The template details are now displayed.
 +4. Make the template modifications. The first change enables the [Save] button.
 +5. Click [Save] to save the changes to the template.
 +6. Click [Exit] to close the window.
 +
 + 
 +Windward-specific document conventions ​
 +The following information is a topic within the help file entitled Help Conventions. Currently the help doesn’t consistently follow these conventions but we are aiming to make it so.
 +
 +Document Conventions
 +
 +The following conventions have been used throughout the System Five help file. The notations detailed in Table 1 are used in all Windward Software products. The information in Table 2 details the standards used when referring to screen components. Included in this topic are instructions for using the help to get to the information you want.
 +
 +Style Indication or meaning
 +[Button] Bold text enclosed in square brackets refers to a button.
 +Screen or tab title Bold text not in brackets, refers to the title of dialog boxes, windows and tabs in <​TITLE>​. ​ This format is also used to refer to figures and tables within the documents themselves.
 +Field label Bold italicized text refers to the label of a field.
 +"​Option"​ Bold text enclosed in double-quotes refers to an option in a drop-down list.
 +<​KEYBOARD>​ Capitalized text enclosed by the less than and greater than symbols indicates a key on the keyboard such as <​ENTER>​ or <​SHIFT>​.
 +Important Notes Bold text in 8 point font, denotes important notes that you should be aware of when doing something with the system.
 +Warnings Bold red text in 8 point font, denotes a warning or optional setting within <​TITLE>​ that has an affect on how the system operates or reacts.
 +Topic Links Text that is green and underlined indicates a link or jump to another area of the Help.  These links may appear in bold, 8 point font if they are included in an Important Note or Warning.
 +Topic Headers Bold, 12 point, underlined text indicates the highest level heading (for example an overview of a window'​s purpose).
 +Section Headers Bold,​ 12 point, indicates a secondary level heading subordinate to the higher level heading (for example a description of a window'​s components).
 +Menu Paths All references to menu paths are displayed in bold, italicized text. When a menu path contains more than one element, the elements are separated by the > (greater than symbol).
 +Internet Links Links to web pages and Web sites are indicated by underlined, blue text.  These links will open the target document in your internet browser.
 +Table 1: The Document notation conventions
 + 
 +
 +Component Description
 +Screen A screen is referred to specifically as either a window (has a Toolbar) or a dialog box (doesn'​t have a Toolbar).
 + 
 +Menu bar
 + 
 +List of Commands
 + A menu bar is located at the top of a window and contains a group of titles that when clicked provide a drop-down list of commands (related to the menu title) to chose from. 
 +
 + 
 +Toolbar
 +  A Toolbar is located close to the top of a window (usually just under the menu bar) and contains a group of buttons that execute an action related to the button title. A small down-arrow beside a button indicates the button has a drop-down list of sub-commands to chose from.
 + 
 +Grid A grid is a group of cells organized in a row to relate to an object (i.e., part) and in columns that relate the same characteristic for a different object (i.e., description). Many of the grids can be exported or customized by right-clicking and selecting the appropriate command from the pop-up menu. 
 + 
 +Check box A check box allows you to select one or more options in a group. When checked the option is selected. When clear the option is NOT selected.
 + 
 +Option buttons An option button allows you to select only one of many options in a group. The selected option has a black dot.
 +
 + 
 +Drop-down combo box A drop-down combo box can work alone or in coordination with other screen components. type directly in the box or click the down-arrow and select one item from the drop-down list of choices
 + 
 +Text box A text box allows you to type in information directly. Some have a restricted format for the information, ​ for example, in the case of a date. 
 + 
 +Button An action button either performs an action directly or opens a dialog box or window for you to perform the entitled action within. ​
 +Table 2: The screen components
 +
 +
 +Using the Help
 +
 +The Help Table of Contents (TOC) is organized similar to the System Five Navigator menu. The only exception is the Welcome section which includes business basics and start up configuration information. Although the TOC is commonly used to find information in books, it is not typical of the way a help file is used to find information. Typically, you look for help for the following two reasons. ​
 +
 +To search for a 'how to' topic: ​
 +
 +1. Select the Documentation command from the Help menu. The Help file appears. ​
 +2. Click on the Search tab, enter key words for your search and click [List Topics]. The topics matching your search appear in the list. 
 +3. Scan the list for the most likely topic to answer your question and click on that topic in the list. The topic text appears in the right panel. Repeat until you find what you are looking for. 
 +
 + Note: If you see the instructional information but want to know how to get to the correct place in <​TITLE>,​ after you search for and select a topic, click the Contents tab. Because the Help TOC reflects the navigator path, knowing where the topic is in the TOC hierarchy helps you understand the navigator path you follow. This is true of all section topics except the Welcome section. ​
 +
 +To find out what a particular item on a screen does: 
 +
 +1. When in the screen you have a question about, click < F1> on your keyboard. The Help file appears with that window or dialog box topic displayed in the right panel. ​
 +2. Find the item you have a question about in the table describing that screen'​s components. In the case of a multiple tab window, you may need to click a link in the window description topic that takes you to the tab description topic. Some of the more complex screen topics have jumps to the individual component descriptions (so you don't have to scroll through a long topic ). 
 +
 +
 +
  
training/docs_style_guide.txt · Last modified: 2010/07/30 13:02 by charlene