NexJ writing style conventions
Reference the following NexJ style guidelines for assistance in customizing and creating documentation with standardized terminology, structure, voice, and appearance.
NexJ writing style
NexJ documentation uses a minimalistic writing style which relies on short words and simple sentence structures as much as possible.
The NexJ writing style uses the following guiding principles:
- Write in a clear, simple, professional style.
- Write in the active voice.
- Write in the second person. Refer to the user of the application or reader of the document as "you."
- Always use complete sentences.
- Write using American, rather than British or Canadian, spelling.
- Use full words instead of truncations. For instance, say "application server" rather than "app server."
- Use the serial, or Oxford, comma.
- Only capitalize proper nouns. Avoid using capitalization as a device to draw attention to key words.
- When in doubt, consult the Chicago Manual of Style 16th edition and the style guides of Microsoft, IBM, and general usage procedures on the Internet for guidance.
Topic and section titles
Titles should be concise and descriptive.
Titles serve two primary functions:
- Provide readers with insight about the topic's content.
- Influence how and where the topic will appear in search results.
Topic titles are written using sentence, rather than headline, style. Only the first word and proper nouns should be capitalized.
Topics and sections dealing primarily with task-related information (how to do something) should have titles that begin with present participles. This informs the reader that the information will help them perform an action. For example a task topic that discusses how to search for files in the search bar would be titled "Searching for files using the search bar."
Topics and sections dealing primarily with reference or conceptual information can begin with nouns, noun phrases, and other parts of speech.
Referencing user interface elements
Refer to the following table for direction on how to format user interface elements:
Element | Example |
---|---|
Buttons | Action button, Delete button, Edit button |
Tabs | Topics tab, Maps tab, Images tab |
Fields | Name field, Description field, List field |
Menu items | File > New > New Project |
Checkboxes | Confirm checkbox, Agree checkbox, Exclude checkbox |
Options | Public, Private, Group |
Code variables
Code variables are surrounded by the inequality symbols < and >. For example:use <modelName>;
where <modelName>
is your model's name.
Vocabulary guidelines
NexJ documentation projects use an established set of technical vocabulary and terminology. Follow these guidelines when customizing the provided documentation projects to remain consistent and prevent confusion by using the same terms throughout your guides.
The following are established word and term use cases to help keep your documentation projects clear and consistent:
Term | Preferred use | Notes |
---|---|---|
attribute vs. property |
| |
cannot vs. can not | cannot | Use cannot, unless not is part of a separate phrase. |
check box vs. checkbox | checkbox | |
file name vs. filename |
| |
follow up vs. follow-up vs. followup |
| |
Internet vs. internet |
| Internet is a proper noun and must be capitalized. |
Intranet vs. intranet |
| Intranet is not a proper noun and should not be capitalized. |
login vs. log in vs. log-in |
| |
once vs. after |
| Once should only be used in terms of numeric counting, but should ultimately be avoided. Use after to indicate the relative ordering of actions that you are describing. |
window vs. dialog |
| Window is a general term, that is applicable to many screens. Use dialog to describe a pop-up window that appears when an action is taken. |
roll up vs. rollup |
| |
run time vs. run-time vs. runtime |
| Use runtime only when quoting another entity`s use of that spelling. For example JRE (Java Runtime Environment). |
SQL |
| For example, "Use the drop command to generate an SQL script for dropping a database schema." |
toolbar vs. tool bar |
| |
user name vs. username |
| Generally, prefer user name, unless there is a valid reason to avoid doing so, such as when explicitly referring to an item named "username" or if user name would be confusing in the context of the content. |
wild card vs. wildcard |
| Use wildcard, especially in the context of a wildcard character. |
drop-down vs. dropdown vs. drop down |
| Avoid using drop-down in most situations. The field you are selecting content for can be referred to without mentioning the drop-down. For example, "In the Saved List field, select the contact you want to add to the saved list." |
Wi-Fi vs. wireless |
| |
/ (standing is for "and" or "or") |
| Use "and" or "or" as appropriate instead of a slash. |
File extensions
File extensions are referred to in a uniform manner.
If you are mentioning a file name with an extension, the extension should be in lower case.
For example, file.bat
.
If you are mentioning just the file type, use upper case.
For example, BAT file.
Documenting common actions
Use standardized terminology when discussing common actions and user interactions with NexJ applications.
Common actions should be referred to in a consistent manner throughout your documentation projects to prevent confusion and misunderstandings. The following guidelines should be consulted when customizing or creating topics:
Clicking and right-clicking
Click or right-click screen elements.
For example:
- Click the Action button.
- Right-click the task.
Selecting
Select menu items, options, or checkboxes.
For example:
- Right-click the task and select Properties.
- Select the Set Status to Complete checkbox.
Pressing
Press keyboard keys.
For example:
- Press Enter.
- Press CTRL + S.
Workspaces and tabs
On the XXX workspace (not in the workspace).
In the XXX tab (not on the tab).
For example:
• On the Schedule workspace, select the Tasks tab.
• In the Details tab, click Edit.
Action buttons
Click the Action button for the item (not of the item).
For example:
- Click the Action button for the task item and select.
- Click the Action button for the document and select.