Bungee Documentation Style Guide

Page Status: Beta
Jump to: navigation, search

Back to Main Page

 

Note Like any entity producing content, Bungee Labs has developed a proprietary style for documentation. Please follow these conventions when editing or adding content to any portion of this wiki. For information on how to apply the styles in the editor, see How to Use this Wiki.

 

Contents

[edit] Formatting

[edit] Control and Property Names

Use bold for control and property names.

[edit] Examples

  • The Label control displays non-editable text.

[edit] Keyboard Keys

When instructing the reader to use a keyboard key, use “press” (not “hit”) and put the key name in bold.

[edit] Examples

  • Press Ctrl-S to save your document.
  • Press Tab or Enter to commit your change.
  • Right-click on any node to select the root.

[edit] Variables

Use italics for variable names.

Example:
  • editChooser ( [in] string type, [in] Object rootContext )

where: type is argument description

rootContext is argument description

[edit] Images

When adding images to a document, create a small version (480 px wide) that is placed in the document. Use Wiki markup for links to lin the small image to a separate page containing the full-size image.

The markup would look like this: <insert image here>

[edit] Adapters

In speaking about adapters and how they are used, use the following verbs and nouns in the appropriate situations:

  • Assign—"Use the Drag Function property to assign a function adapter to a control."
  • Identify—"Form adapters provide a way to identify a form."
  • Interface—"Function Adapters provide an interface for locating the right function to use for a given action, such as a double-click action or a drag-and-drop action."
  • Add—"You add an adapter at the project level of a solution. This is neccessary so that every adapter in your project is in the proper scope to be assigned to any Model or View element in your project."

[edit] Connection

 In speaking about adapters and how they are used, use the following verbs and nouns in the appropriate situations:

  • Implement—"Connections implement connection adapters."

[edit] Affect Versus Effect

Which of these sentences are correct?

1. Rising oil prices will have an effect on nearly everyone.
2. Her emotional outburst was purely for effect.
3. The new policies go into effect next month.
4. The trade embargo effected the rise in oil prices.
5. Rising oil prices affect nearly everyone.
6. The elderly couple next door was severely affected by the cold this winter.
7. The psychologist on the witness stand noted the alleged murderer�s disturbing affect during the confession.

All of these sentences correctly employ "effect" and "affect."

In most situations, we use "effect" as a noun and "affect" as a verb.

To clarify the difference between the most common uses of "effect" and "affect," remember that the noun "effect" often will follow an article ("an effect," "the effect") or an adjective ("negative effect," "positive effect"). Sentence 1 provides an example of such a construction. Nouns are also used as objects of prepositions as in sentences 2 and 3 ("for effect," "into effect").

Webster's Tenth tells us that the verb "effect" means "to cause to come into being" or "to bring about, often by surmounting obstacles." When you are tempted to use "effect" as a verb, ask yourself if the phrase "bring about" makes sense in its place. Notice that in sentence 4 we could have just as easily said "The trade embargo brought about the rise in oil prices." Consider the difference between saying "the embargo affected oil prices" or "the embargo effected oil prices." The former phrase tells us that the embargo had an impact (an effect) on the prices, but the latter phrase illogically suggests that the embargo brought about the oil prices.

In the majority of sentences, when we need a verb, we should use "affect," as we see in sentences 5 and 6. Unless we are in the medical field, most of us will rarely if ever use "affect" as a noun, but in the field of psychology it refers to an emotional state (see sentence 7).

 

 

[edit] About Versus On 

Use "about" when you direct users to look for additional information somewhere else.

[edit] Examples

Preferred: For information about the Bungee Licensing, see Chapter 3.

Acceptable, but not preferred: For information on the Bungee Licensing, see Chapter 3.

[edit] Capitalization

In general, if an article or another limiting word (a, the, this, some, or certain) appears before the noun in question, it is a common noun.

[edit] Examples

  • Use a text editor to change information in the file.
  • Use Text Editor to change information in the file.

Note Be aware of the difference in these two sentences. In the first sentence, the article a makes it clear the writer is talking about a generic text editor. In the second sentence, the absence of an article makes it clear the writer is talking about a specific text editor, thereforeText Editor is capitalized.

In general, capitalize:

  • Most acronyms
  • Chapter when followed by a letter or number
    Examples:
    Turn to Chapter 3.
    Turn to the next chapter.
  • The first letter of the names of function keys on a keyboard
    Examples:
    Control key
    Escape key.
  • The first letter of the first word of a sentence
    Example:
    Format allows you to divide the disk into partitions
  • The first letter of any word in a title or head, with the exception of conjunctions and articles, prepositions of fewer than four characters, and the “to” in infinitives, unless they appear at the beginning or end of the title or head
    Example:
    See Chapter 3, “Splitting the Infinitive.”
  • The word page or step when it is followed by a number
    Example:
    see Page 45.
  • The second element of a hyphenated compound in a title or head only if it is a proper noun or adjective, or if it has equal force with the first element
    Example:
    Ordering Third-Party peripherals
  • The word web
    Examples:
    web si t e
    web browser
    webmaster
    getting information from the web

[edit] Abbreviations

Use lowercase letters for abbreviations unless the term abbreviated is a proper noun.

[edit]  Headings

As a general rule, when creating a heading on a wiki page, use a gerund (a word ending in "ing").

[edit] Examples

  • Correct: Building an Application 
  • Incorrect: How to Build an Application

[edit]  Capitalization in Headings and Titles

  • Capitalize the first letter of each major word
  • Do not capitalize articles, coordinating conjunctions, or prepositions, regardless of the length, unless the article, conjunction or preposition follows a colon, or is the first or last word in the title or heading
  • Do not capitalize the word to as a part of an infinitive unless it is the first word in the heading or title

[edit] Enter Versus Type

Enter is frequently confused with type. Enter means to "go into" or "join." Type means to "key" words into a data field.

[edit]  Examples

  • Right: Type the domain name...
  • Wrong: Enter the domain name...

[edit] Dialog Box

A dialog box contains command buttons and various kinds of options through which users can carry out a particular command or task. The name of the dialog box is boldface, initial cap each word, but the words “dialog box” are not.

[edit] Dialog Box Syntax

These terms are most commonly used for user actions in dialog boxes:

  • Click. Use for commands, command buttons, option buttons, and options in a list, gallery, or palette. Do not include the word “button” when describing where the user should click. For example:

Correct: Click OK.

Incorrect: Click the OK button.

  • Select or clear. Use for check boxes.
  • Type or select. Use to refer to an item that a user can either type or select in a text box.
  • Choose or select. Use these terms only when documenting generic procedures. Use choose for commands, and select for options. Example: From the Options menu, choose Preference to display the Preferences dialog box.
Note: We’ve been using select extensively in the docs, so let’s continue using select.

[edit] Procedures

A procedure is a short description of the steps a user takes to complete a specific task. A procedure is presented as a numbered list with an introductory phrase. The general rules for lists also apply to procedure lists. There are two types of procedure lists: multi-step and single-step procedures.

[edit] Multi-Step Procedures

The general rules for lists also apply to procedure lists.

  • Make steps separate, numbered entries. You can combine small steps that occur in the same dialog box into one step.
  • Use parallel construction.
  • Use proper punctuation and capitalization.
  • Do not combine steps and step results into one step. Make the step result an indented paragraph under the step.

[edit] Single-Step Procedures

Do not number single step procedures. The following is an example of a single step procedure:

To change the name of a function:
In the textbox for the Name property, replace the default text with the new name for the function.

[edit] Procedural Syntax

Tell the user where the action takes place, then describe the action.

[edit] For Folders and Icons

Users click or double-click a folder or icon to initiate an action.

[edit] Commands

Use the following syntax for commands:

From the File menu, choose Save.

 

 

 

    Copyright © 2005 - 2007 Bungee Labs. All rights reserved.