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.
This section describes recommendations for terms in technical documentation, explanations for why they should be used or avoided, and suggestions for their alternatives.
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.
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.
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.
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.
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
- 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.
- "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)
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)
- 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.