Formatting Standards

This page relies on the use of MediaWiki, not Markdown. We will soon be migrating all articles to MediaWiki, at which point this page will become vaguely--as opposed to not at all--relevant.

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.

Table of Contents

• Section Headers
  • Developer Tutorials
  • Documentation
  • User Tutorials
• Body Paragraphs
  • Processes
  • Using Tables
• 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

The hierarchy should resemble the following:

1. Background
2. Installation

Body Paragraphs

Processes

1. When explaining a sequence of clicks, use carrots.

Using Tables

Generally, we use tables when we need to provide a collection of related, multi-linked data. (Multi-linked in the sense that multiple factors, which also need to be given, correspond to one piece of data). Most commonly, tables come out when we are explaining the parameters, methods, or parts of assorted NiCE classes and interfaces. You should not use tables for ordinary vocabulary definitions.

Most commonly, the table would be formatted something like this:

 Name of Class

 Parameter  Default Value  Explanation

 Parameter 1 
 Default Value 1 
 Explanation 1

 Parameter 2 
 Default Value 2 
 Explanation 2

 Parameter 3 
 Default Value 3 
 Explanation 3

This table would look like this:

Name of Class

Parameter Default Value Explanation

Parameter 1
Default Value 1
Explanation 1

Parameter 2
Default Value 2
Explanation 2

Parameter 3
Default Value 3
Explanation 3

Obviously, you could change the heading to suit your own needs. The boxes self-expand based on how much text you enter, but retain a consistent size by column (for this particular table).

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

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

To type in code font, type the following:

<pre>

Text here. We add the tags to increase font size, because the default code font looks

like this

, which becomes irritating very quickly.

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.