Formatting_Standards

As NiCE continues to evolve, more and more articles must be created and maintained in order to keep the NiCE project self-aware and accessible. The goal of this page is to make the expanding volume less stressful for everyone. By standardizing certain types of pages, such as tutorials or documentation, readers will more easily browse and find what they need. Consistency also eases the editors' burden, because making updates and spotting errors becomes simpler when everything should look the same.

That being said, there are many different types of beneficial pages, and not all can precisely conform to a style. These are mere guidelines.

• Section Headers
  • Developer Tutorials
  • Documentation
  • User Tutorials
• Body Paragraphs
  • General
  • Developer Tutorials
  • Documentation
  • User Tutorials
• Formatting Text
  • Bold
  • Italics
  • 'Code' Font
• Keeping Word Count Down

Section Headers

Section headings are your best friend. They streamline long articles by allowing the reader to quickly locate particular information. To facilitate the realization of this benefit, headings should stay consistent among sections of the same purpose within different articles.

Developer Tutorials

Documentation

User Tutorials

Body Paragraphs

General

Developer Tutorials

Documentation

User Tutorials

Formatting Text

Our articles assume a basic comprehension of computer science jargon, but NiCE has its own vocabulary to add to the mix. To avoid overwhelming first-time users, textual formatting should stay consistent. This helps readers automatically categorize and sift through terminology more efficiently.

Bold

The bold functionality (arguably) is the most eye-catching and should be used sparingly.
NiCE wiki editors bold to denote:

• an especially important instance of a soon-to-be common word
• introducing and defining a named NiCE feature.
• introducing and defining a term.
• special comments
• "Tips" - helpful hints and/or shortcuts. The tip itself stays plain. (Example - Tip: Sharing common rules helps establish harmony.)
• "Notes" - admissions of bugs or limitations. The note itself stays plain. (Example - Note: However, we will never be perfect.)

Italics

Italics are less dramatic. They place emphasis on a word within the sentence, rather than within the whole section.
NiCE wiki editors italicize to denote:

• variables
• labelled areas of the user interface

'Code' Font

The default code font looks

like this

and becomes irritatingly very quickly, which is why we always increase the size to make it look

like this

.

NiCE wiki editors use the code font to denote:

• directories
• files and file locations
• commands (for the command line interface)
• keyboard keys
• any text users must type
• methods

Keeping Word Count Down

These suggestions may seem finicky, but little differences stack up over the course of a whole page.
1. Avoid the passive voice.

• Instead of, "The interface should be implemented by the class," say, "The class should implement the interface."
• Sentences written in the active voice are also easier to read.

2. Eliminate subjunctive expressions.

• Rather than saying, "It is necessary/important that..." use "should" or give actual instructions.
• You'll make a more direct connection with the reader.
• Always give a reason; that is worthy of taking up space. Users and developers are far less likely to encounter problems if they understand the process.

3. Keep your prepositional phrases efficient.

• Why say, "in order to..." when "to..." will do just as well?
• If possible, use possessive language instead of prepositions.