DocEditorialGuidelines

NetBeans Guidelines for Community Contributions

The following guidelines are meant to help you create clear, concise documentation when contributing to the NetBeans community. These are only suggestions, not rules, but they should answer questions about word use and terminology that might arise when working with NetBeans.

Many of these guidelines stem from the need to write in a way that makes a document easily translatable into other languages. Certain words and phrases are difficult to translate into other languages. With careful consideration, those instances can be avoided and thus a document created that can be translated into various languages and used on a global scale.

Terms Usage

This section describes recommendations for terms in technical documentation, explanations for why they should be used or avoided, and suggestions for their alternatives.

Word Choice

  • Pronouns

Use pronouns such as "it," "its," "this," "they," "theirs," "that," "these," and "those," only when the noun to which the pronoun refers is clear.

Incorrect: This provides the following benefits.
Correct: This support provides the following benefits.

  • Jargon and Slang

Use terms that are listed in standard dictionaries or technical source books. If translators cannot look up an unfamiliar term, they might have to guess at its meaning.

  • Idioms and Nonstandard Colloquialisms

Nonnative English speakers often misunderstand idioms and nonstandard colloquialisms because they interpret these terms literally.

For example, a screen doesn’t "come up", it appears. Likewise, you do not "do a deploy", you "deploy" something. Avoid using idioms and nonstandard colloquialisms.

  • Superfluous Terms

When possible, eliminate words such as "simply", "easily" and "just". Eliminating them will make the document more concise and easier to read. Likewise, the phrases "first of all" and "firsthand" can be eliminated from documentation.

  • Foreign Words

Even though some foreign terms are listed in U.S. English standard dictionaries, do not use them in your documents. Nonnative English speakers might not understand foreign terms such as "vis-à-vis," "via," and "vice versa." In addition, when documents are translated, no equivalent terms exist for foreign terms in target languages.

  • Commands

For literal command names or other computer terms, include a phrase such as "the ... command" or "the ... function" on first reference. Including the surrounding article and term can clarify all references.

Specific Words and Phrases

  • Available and Unavailable

Be careful about using the word "available" because it has multiple meanings. Where possible, use definitive words such as "active" or "valid."

Incorrect: The role determines the user's available permissions.
Correct: The role determines the user's valid permissions.

Incorrect: After you add the entry, the Edit button becomes available.
Correct: After you add the entry, the Edit button becomes active.

However, the following are acceptable uses of "available" and "unavailable":

Further information is available at http://www.sun.com.
Go to the First Page (Unavailable)
If additional disk space is unavailable, the program fails.

  • May

Use the word "may" only when you mean permission, as in "You may use these conventions in your code."

Use the words "might" or "can" in place of the word "may" whenever possible. The word "might" indicates a possibility, and "can" means the power or ability to do something. A translator who must translate the English word "may" in text often chooses whether to translate it as "can" or "might." The original writer is in a better position to know which word is more accurate and should therefore use the correct word.

  • Recommend that

Rephrase "recommend that" or "It is recommended to" and start with the benefit of the behavior. Instead of saying "It is recommended to use the application's class name as the volume name," say "To ensure that the volume name is unique and meaningful, use the application's class name as the volume name."

Incorrect: We recommend that you install the custom components only on large systems.
Correct: Install the custom components only on large systems.

Incorrect: We can write a protocol specification that describes the remote version of printmessage().
Correct: You can write a protocol specification that describes the remote version of printmessage().

Incorrect: Let's assume that the user already has an account on the system.
Correct: Assume that the user already has an account on the system.

  • That

Include the word "that" when it is used to introduce a restrictive clause.

Incorrect: Verify your configuration matches what is shown in the example.
Correct: Verify that your configuration matches what is shown in the example.

  • There and It

Avoid using the words "there" and "it" at the beginning of a sentence or independent clause if those words take the place of the subject of the sentence and are followed by a linking verb such as "is" or "are."

This construction delays the subject of the sentence, which can confuse translators.

Incorrect: There are only a few troubleshooting tickets left.
Correct: Only a few troubleshooting tickets are left.

Incorrect: It is a simple path.
Correct: The path is simple.

Incorrect: In command-line mode, there are two ways to delete a file.
Correct: In command-line mode, you can delete a file in one of two ways.

  • We

For the most part, readers of your online contributions will not know who you are. Refrain from using the term "we", as it can sound condescending in English to the reader. So, instead of saying "We recommend that you remove the cover first," tell the reader "Remove the cover first."

  • When and If

Be precise about using the words "when" and "if." Use "when" for an inevitable event, and "if" for a conditional event.

"When the prompt is displayed" implies that the prompt will be displayed.
"If the prompt is displayed" implies that the prompt might or might not be displayed.

Tips for Clarity

  • Use Terms Consistently
Avoid using terms that can have several different meanings.


For example, the word "system" can refer to an operating system (OS), a combination of OS and hardware, or a networking configuration. If you do use such a term, ensure that you define it and use it consistently in a document. Ensure that you also add it to the glossary.


Use terms consistently throughout a document.


Synonymous terms in a document can be troublesome for a translator. The words "show," "display," and "appear" might seem similar enough to use interchangeably. However, a translator might think you used the different words deliberately for different meanings, and a translator might interpret the text incorrectly.


Instead of using synonymous terms in a document, pick one term and use it consistently throughout your document or documentation set.


Other inconsistent usage with which translators might have trouble include the following
Down, crash
Menu option, menu item
Connector, port, plug
Output, result
Some, several, many, few
Platform, architecture, system
Scroll list, scrolling list, scrollable list


Executables, executable program, executable code, executable application, executable file


  • Avoid ambiguous phrases
For example, "first-come, first-served" is ambiguous. If possible, rewrite as "in the order received" or "in the order in which they are received."


Also, watch for words that could lead to unguided choices. Avoid the following ambivalent words and phrases
It is possible to
Maybe
Perhaps
Either, or
If you want
Should, would


When you write these words or phrases, or similar ones, make sure that you are prepared to explain the benefits of the choices.


Example
"After uploading the file, you should see the following pop-up window."


With the sentence above, the reader will not know what to do if they do not see the pop-up window. Rewrite this sentence as follows


"After uploading the fill, you see the following pop-up window. If the window does not appear, confirm that the file was successfully uploaded by locating it in the XYZ location."

(the above taken from Ch. 3 and 8 of ESG)

Grammar Guidelines

If you adhere to English grammar guidelines and use terms correctly in your documentation, you can eliminate much of the ambiguity that slows the translation process. The following is a list of recommended grammar guidelines.

  • Capitalize consistently

Use uppercase and lowercase letters consistently in like elements throughout a document.

Using consistent case helps a translator determine the proper interpretation of a term. The use of consistent case is significant for reserved keywords, class names, and variables.

  • Check spelling

Ensure that spelling and word usage are correct. Use electronic spelling checkers and copy editors to ensure accuracy.

  • Include verbs

Be sure to include verbs in sentences. Double check your sentences to be sure you have included all necessary words, so that the reader understands what you are saying.

  • Include articles

Be sure to include articles such as "the," "a," and "an" when appropriate.

Incorrect: Place screwdriver in groove.
Correct: Place the screwdriver in the groove.

"The" is used to refer to specific or particular nouns; "a/an" is used to modify non-specific or non-particular nouns. The is a definite article and a/an an indefinite article.

"The" is called a definite article and is used to refer to a specific or particular member of a group. Limited.
"A/an" is called an indefinite article and is used to refer to any of a certain group (not a particular member of a group). Unlimited.

"The" can be omitted with non-countable nouns. "I love to upload new software."

"An" precedes only nouns that begin with a vowel. Vowels are a, e, i, o, u.

Incorrect For more information, see the Chapter Two.
No article is needed because there is only one Chapter Two

Correct For more information, see the section on uploading new software

This sentence requires "the" because you are referring to a specific section. You would not write "see a section" because then the reader would think there are many sections on this topic. It is common to omit the article in cross references.

Correct For more information, see System Administration Guide: Solaris Containers-Resource Management and Solaris Zones.

For a summary of features that were introduced in the Solaris 9, Solaris 8, or Solaris 7 releases, see What's New in the Solaris 9 Operating Environment at http://docs.sun.com

Good rule of thumb: "a" means one or any (of a group of things)

Additional examples:

Put the cursor over a tab. (any tab)
Select the tab by clicking it. (a specific tab)
"This section describes the printing capabilities for tables and explains how to add printing support to your applications."
"Note that the total number of pages in the output is not known before printing time."
"Both width and height are scaled to provide an output of the same aspect ratio."
"...enables the user to turn off the displayed print dialog." (Not: "provides links to an appropriate sections.")


  • Avoid Passive Voice

Avoid passive clauses, such as "the program was activated." Instead, write "Active the program." Or, "The program starts after you perform the following steps."

  • Do not put a list in the middle of a sentence
  • Prepositional Phrases

Check for the correct placement of prepositional phrases.

Incorrect: Remove the filler panel from the slot with the pliers.
Correct: Use pliers to remove the filler panel from the slot.

  • Be careful about using the same term in multiple grammatical categories, such as verb, noun, and adjective

Incorrect: Plug the plug into the wall outlet.
Correct: Connect the plug to the wall outlet.

Using "plug" as both a verb and a noun is confusing to translators. Translators might have to use a different term in each case. Also, do not use several terms to refer to the same thing.

Examples of Commonly Misused Phrases:

Incorrect: On the screen that comes up…/ On the screen that will come up…
Correct: On the screen that appears.

Incorrect: The code looks like below. The project structure looks as shown below.
Correct: The code appears as follows. The project structure appears as follows.

Incorrect: Do a deploy.
Correct: Deploy the program. Deploy the application.

Incorrect: After doing necessary changes,
Correct: After performing the necessary changes; After making the necessary changes,

Incorrect: Go ahead and start the application.
Correct: Start the application.

Avoid the word "as" in phrases that include the verb "to name" or "to rename".

Incorrect: Name the element as "Blue Suede Shoes." Rename the file as "text".
Correct: Name the element "Blue Suede Shoes." Rename the file "text".

The terms "double-click" and "right-click" are both lowercased and hyphenated and do not use a preposition.

Incorrect: Perform a Right Click on the dialogue box and choose "run". Then doubleclick at the name file. A new dialogue box appears.
Correct: Right-click the dialogue box. Then double-click the name file.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo