NexJ Logo

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:

ButtonsAction button, Delete button, Edit button
TabsTopics tab, Maps tab, Images tab
FieldsName field, Description field, List field
Menu itemsFile > New > New Project
CheckboxesConfirm checkbox, Agree checkbox, Exclude checkbox
OptionsPublic, 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:

TermPreferred useNotes
attribute vs. property
  • attribute = when referring to class attributes added by users in the Attribute tab
  • property = when referring to the properties of an object, or values updated in the Properties view

cannot vs. can notcannotUse cannot, unless not is part of a
separate phrase.
check box vs. checkboxcheckbox
file name vs. filename
  • file name = noun
  • filename = As an adjective or variable name in situations where the space would be confusing

follow up vs. follow-up vs.
  • follow up = verb
  • follow-up = noun and adjective
  • followup = avoid using

Internet vs. internet
  • Internet
Internet is a proper noun and must
be capitalized.
Intranet vs. intranet
  • intranet
Intranet is not a proper noun and
should not be capitalized.
login vs. log in vs. log-in
  • log in = verb
  • login = all other uses
  • log-in = do not use

once vs. after
  • 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
  • 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
  • roll up = verb
  • rollup = adjective

run time vs. run-time vs.
  • run time = noun
  • run-time = adjective
  • runtime = do not use
Use runtime only when quoting another entity`s use of that spelling. For example JRE (Java Runtime
  • Pronounced and used as an acronym. Not as the word "sequel
For example, "Use the drop command to generate an SQL script for dropping a database schema."
toolbar vs. tool bar
  • toolbar

user name vs. username
  • user name
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
  • wildcard
Use wildcard, especially in the context of a wildcard character.
drop-down vs. dropdown
vs. drop down
  • 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
  • Wi-Fi = when discussing Wi-Fi certified network technologies and networks
  • wireless = when referring to general wireless connectivity

/ (standing is for "and" or "or")
  • Avoid
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.

Select menu items, options, or checkboxes.

For example:

  • Right-click the task and select Properties.
  • Select the Set Status to Complete checkbox.

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.