Writing Guidelines & Terminology

The following table defines the basic standards implemented to ensure consistency throughout all documentation, both online and print, unless otherwise noted.

Element	Description	Correct Example	Incorrect Example
Abbreviations/Acronyms	The first time an abbreviation/acronym appears in a document, spell out the full name and put the abbreviation/acronym in parenthesis. After it has been spelled out, all other references can be the abbreviation or acronym.	Data Stewardship Platform (DSP®)	Data Stewardship Platform – DSP®
Action Verb when appropriate	Start all steps with a present tense action verb.	Click Add. Select an option from User list box.	On the Page Toolbar, click Add. From the User list box, select an option.
Serial Comma	Do not use a serial comma with “and” or “or,” i.e., when listing items in a sentence, do not insert a comma before the “and” or the “or” to introduce the last item in the list.	Enter name, address and phone number.	Enter the name, address, and phone number.
Icons	Refer to UI elements like this as icons. Identify the icon as such in the steps.	Click the Process Areas icon.	Click Process Areas.
Button	Refer to UI elements like the Clear Cache one below as a button. Do not include the word “button” for buttons in the Page toolbar, such as Save, Edit or Add. These button are always in the same place, so there’s no need to qualify them.	Click Add.	Click the Add button.
Capitalization	In general, do not capitalize application terminology such as roles, scenarios and column properties unless indicating a particular term. NOTE: Field names in the documentation must match the field names in the product. If the product contains a capitalization error, documentation must reflect this. The following are always capitalized: Check box names Column heading names Dialog box names Field names Headers Icon names Keyboard names List box names Menu options Toolbars Page names Section names Tab names Value of field names unless generic value of list box names Window names WebApps Controls Environment names (in all capital letters)	Log in to DEV Click Filter. Click Label to sort column.	Log in to DEV Click filter. Click label column heading to sort column.
Check box (Print)	Use the term “check box.” Bold all check box names in imperative statements. Click a check box. Capitalize check box names.	Click the Update Allowed check box.	Check the Update Allowed check box.
Check box (Online)	Follow standards for print, with these clarifications. Use Cases: When using the check box to add or to edit in numbered steps in a use case, use the standard: “Click the [check box name] check box to [action].” or “Click the [check box name] check box to disable it, allowing [action]” Field Descriptions: When describing a check box in Field Descriptions, use the standard “If checked. . . .” to start the descriptions (or “If unchecked, . . .” if that’s the preferred setting).	Use Case: Click UNIQUE INDEX check box to build a unique index. Field Description: If checked, a unique index is built.	N/A
Code Text	Use body style Use Consolas font Capitalize NULL	The final three columns in the `#AuditProcedure` table are `boaAuditProcedureCounter`, `boaAuditProcedureType` and `boaAuditProcedureName`.	The final three columns in the #AuditProcedure table are boaAuditProcedureCounter, boaAuditProcedureType and boaAuditProcedureName.
Colloquialism, Jargon and popular expressions	Avoid using jargon and popular expressions (Colloquialisms)	Wait until the page loads…	Wait until the page cuts on…
Column Headings	Capitalize column heading names as they appear in the UI. Click a column heading to sort.	Click the Label column heading to sort the column.	Select label column heading to sort column.
Concise Language	Omit needless words.	allow, let to now because during needs quickly, promptly by, following, per, under before to about, concerning, on for if shortly, soon left, right by June 1 about guides under until about except	afford an opportunity as a means of at this point in time due to the fact that during the period has a requirement for in a timely manner in accordance with in advance of in order to in regard to in the amount of in the event that in the near future lef-hand, right-hand no later than June 1 pertaining to provides guidance for under the provisions of until such time as with reference to with the exception of
Currency and numerical formats	Understand international currency and numerical formats. As with date and time formats, provide format standards for reference.
Date and time	Understand international date and time formats. Spell out the month in dates to avoid confusion. If needed provide format standards for reference.	For example, write, “The dates referenced in this article use the MM/DD/YYYY format.” at the beginning of an article. Or add a note, “NOTE: The format for the start and end date is MM/DD/YYYY.”
Definitive Article	Use a definitive article (the, a, an, etc.), except when referring to buttons or the Vertical View as a clickable icon.	Click Request on the Navigation pane. Enter a value in the Priority field.	Click Request on the Navigation pane. Enter a value in Priority field.
Emphasizing Words	When emphasizing a word or an action, format the word in red, bold and all small letters.	Do not click . . .	Do NOT click . . . Do not click . . .
Examples	Use “for example” and “as in” instead of e.g., and i.e.	For example, …; (for example, …)	…, as in… (i.e.,…)
Field Values	Use the standard “Enter [value] in the [field name] field.” Bold the field name.	Enter a WebApp name in the Name field. Select a state from the State list box.	Enter name in the "name" field. Select state from state list box.
Fonts (Print)	See the Styles page for more information.
Headings (Print)	Do not number section headings. Do not indent headings, regardless of the level.	Heading 1 Heading 2 Heading 3	Heading 1 Heading 2 Heading 3
Icons (Print)	Click an icon. Capitalize and bold the icon name.	Click the Targets icon on the Design page.	Select Targets.
Links (Print)	Click a link. Format all links in blue and italicized when a hyperlink exists for the link, such as a reference to a section in the same document or a link to a Web site.	Refer to Page Header for detailed information. Go to www.boaweb.com	Refer to the Page Header section for detailed information.
List Box	Use the term “list box.” For example, Select [a value] from the [list box name] list box. If the user must select a specific value, apply bold formatting to bold that value. If the user can select any value, do not bold the name.	Select Texas from the State list box. Select a value from the City list box.	Choose Texas from State list box. Choose a city from the city list box.
Navigation pane	Standard is “Navigation” is in italics, pane is lower case.	Select Configuration > Data Sources in the Navigation pane.
Mood	Avoid conditional	You can edit the file.	You should edit the file.
NOTE	Use notes to explain additional information, exceptions to rules or features, processes or functionality. Bold the word NOTE and the colon. Present the word NOTE in all caps. Insert the note after the relevant step.	NOTE: Column, Phrase Out and View Type column fields are not editable.	Note: Column, Phrase Out and View Type column fields are not editable.
Numbers	Spell out numbers 1-10 when not associated with a date, dollar amount or measurement.	The Switchboard contains five menu options.	The Switchboard contains 5 menu options.
Or	Use “Or” on a separate line between the options when presenting choices. Use all caps for or “OR” Align “OR” with the beginning of the options it is separating. Do not number or bullet the second option when using “Or” within a numbered or a bulleted list.	Click Save. OR Click Cancel.	Click Save or click Cancel.
Parameters	Use this boilerplate text for all Parameters topics: Parameters are [component name]-specific settings that must be configured per installation. Parameters are delivered with recommended default values. Review these values and make any changes necessary for the installation. To configure trace parameters: Select [Navigation Path] in the Navigation pane. Click Edit. View the field description for the [page name] page Update all fields if default values are not applicable. Click Save.
Page vs. Screen	Use “page” for all BOA web-based applications. Use “screen” for SAP and “window” for all other applications. Capitalize and italicize all page and window names, but not the words “page” or “window”.	The Request page displays.	The Request screen displays. The bottom frame displays.
Password	Describe as asterisks when adding a password in steps.	Displays asterisks representing the password for xxxxx.
Personal Pronouns/Subjects (Online Help)	Do not use “you”, “he”, “she”, “they” etc. NOTE: Starting all steps using action verbs helps avoid personal pronouns and subjects.	Click Add. Complete all steps prior to saving.	The use clicks the Add button. The DSP displays the Add Request page. You should complete all steps prior to saving.
Referencing Written Material (Print)	Italicize references to documents outside of the current document. Italicize and use blue font for references within the current document.
Passive Voice	Avoid the use of passive voice when at all possible. Make it clear who or what performs an action.	Click Vertical View. Collect generates the reports. The Template Administrator configures the template process.	The report is generated. Vertical View should be clicked. The template process is configured.
Punctuation	Use only one space after a period to separate sentences. Put a period at the end of each step. Put a period at the end of each bullet if the bullet is a complete sentence. Be consistent with period use in bulleted lists. Place punctuation outside of parenthesis unless it is a complete sentence in the parenthesis. Avoid entire sentences in parenthesis, if possible.	Click Add.	Click Add
Radio Buttons	Do not use the term radio button. Use option.	Click the Enable option.	Click the enable radio button.
SAP vs. Target System	Use “target system” instead of “SAP” when possible.
Screen Shots (Print)	Include an introductory description if the screen shot is not inserted within steps. Left align or tighten the introductory text with the screen shot if not within steps. Insert the screen shot after the step that references the image when using screen shots within numbered steps. Left align the screen shot with the numbered steps or tighten text of the screen shot to the left if inserting within steps. Do not include a mouse pointer, arrows or text. Put a 1 point black line border around the screen shot. Include a caption to describe the screen shot.
Tables (Print)	Format the first row in the Table Column style. Format the remaining rows in the Table Text style. Bold the first column. Do not use a caption.
Tense	Always use the present tense.	Click the Users button; the Users page displays.	Click the Users button; the Users page will display.
Time	Understand international date and time formats. Spell out the month in dates to avoid confusion. If needed provide format standards for reference.	For example, write, “The dates referenced in this article use the MM/DD/YYYY format.” at the beginning of an article. Or add a note, “NOTE: The format for the start and end date is MM/DD/YYYY.”
Terms	Use terms consistently. For example, do not use edit, change, and update. Select and use only one form of the verb and use it consistently.	To edit the template, click Edit. If you need to edit the description, edit it in the Description text box.	To update the template, click Edit. If you need to change the description, you can edit the Description text box.
Trademarks	The first trademarked product name that appears in a document is followed by the appropriate trademark symbol (™ or ®). All subsequent mentions of the trademarked product name are not followed by a trademark symbol. A list of current trademarks is available from the Legal department or at http://www.boaweb.com/trademarks/ Trademark symbols do not follow the product name if it appears as: Part of a file name Part of a field on a page that does not also contain the trademark symbol	Select the dspcompose.bat file. dspCompose™ is the replacement for cMass.
Verbs	Use the most specific verb possible. This avoids both ambiguity and wordiness, and creates strong writing. Prefer single word verbs to multiple word verbs.	"join"	"Put together"
Views	When used in a sentence outside of a step in a use case: Italicize and capitalize a view name. Do not italicize the word “View.” Capitalize and bold both words.	When used in a sentence outside of a step in a use case: Click the View Data icon on the Vertical View of a request role before import to ensure that the data in the view is appropriate for import into the request. When used in a step in a use case: Click Vertical View for the role that allows data entry.	When used in a sentence outside of a step in a use case: Click the View Data icon on the Vertical View of a request role before import to ensure that the data in the view is appropriate for import into the request. When used in a step in a use case: Click Vertical View for the role that allows data entry.
Voice and Gerunds	Use the active voice not the passive voice. Use the positive voice not the negative voice. Do not use gerunds (a verb that ends in -ing and functions as a noun) in titles or to begin steps.	Click Users; the Users page displays	Clicking Users opens the Users page.