Style Guide

Rule 1: If a word can be linked to a glossary entry or user interface page then link it and add a label.

Rule 2: Never use a long word where a short one will do.

Rule 3: If it is possible to cut a word out, always cut it out.

Rule 4: Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.

Writing Style

The objective for this is to clarify and the concepts of Person vs Mood vs Voice. When writing documentation it is recommended that everything is written using the imperative mood in and active voice.

Grammatical Person

‘You’ (second person singular) - “You should put the plate on the table.”
‘We’ (first person plural) - “We should put the plate on the table.”
‘The user’ (third person singular) - “The user should put the plate on the table.”

Imperative mood

Imperative – “Put the plate on the table.”

Used for instructions, requests or orders

Active vs Passive

The subject of a passive sentence typically denotes the recipient of the action (the patient) rather than the performer (the agent). The passive voice uses the auxiliary verb be (or get) together with the past participle of the main verb.

For example:

 A license can be requested after you get the software installed.

uses the passive voice. The subject denotes the person (software) affected by the action of the verb. The agent is expressed here with the phrase you get, but this can be omitted. The equivalent sentence in active voice is 

Install the software before requesting a license.

in which the subject denotes the doer, or agent, install. 

Abbreviations

Write words in their full form on first appearance unless an abbreviation or acronym is so familiar that it is used more often. In body text use small capitals for abbreviations.

Examples of abbreviations are:

• XML – eXtensible Markup Language.
• PS – PageSeeder.
• HTML – HyperText Markup Language.
• HTTP – HyperText Transfer Protocol.
• XREF – Cross-reference.
• PSML – PageSeeder Markup Language.
• ID – Identifier.

Capitals

Lower case can be used when they are referred to incompletely on the second mention.

Hyphens

There is no firm rule to help you decide which words are run together, hyphenated or left separate. If in doubt, consult a dictionary. However, due to the issues the PageSeeder search function has with finding results for hyphenated words, it is best to avoid them when possible.

For example, use FOConfig instead of FO-Config.

Spelling

Use American English rather than British English or any other kind.

For example, use ‘customization’ instead of ‘customisation’.

Numbering

With lists, headings or paragraphs, numbering should only be used to express a sequence. It should not be used as decoration.

Lists

When using emphasis in list items, separate the emphasized text from the rest of the item using an en dash character ‘–’ (alt+0150).

• HTTP – HyperText Transfer Protocol.
• XREF – Cross Reference.
• PSML – PageSeeder Markup Language.

List punctuation

In general, longer list items should start with a capital and end with a comma or semi-colon, then full stop at end of  last item in a list.

Where list items are short, eg a topic or xref, initial lower case and no end punctuation is acceptable.

Headers

Language Conventions

Terms

In the PageSeeder documentation, ‘Document’ is ambiguous. Correct usage is to pair it with a qualifier. Examples include:

• “Although they can exist the same zip package, upon upload, PageSeeder documents are treated differently that non-PageSeeder documents.”
• “To create high quality publications from Word documents, nothing is more important than the consistent use of styles.”

Hyphens

Hyphens create problems for users searching the collection. They are treated like spaces in Lucene, which leads to a situation where terms that are on the page, are not returned in the results of a search.

• Login not log-in.
• XSLFO not XSL-FO.
• FOConfig not FO-Config.

Hyphens should be reserved for compound terms like:

• “Adobe InDesign can be used to add high-end composition capabilities to PageSeeder”.

Instructions

When instructing the user to interact with the system, following these conventions for the use of verbs helps to make the documentation consistent. 

• List – is generally meant for a simple list of items. For example:
• “List the members of the group”.
• Browse – is used for more complex, multi-dimensional structures, including:
• “A simple technique for gross error checking the content of a group is to browse the facets on the Search page”.
• View – is used for single items:
• “View the Section Template”.
• Show – should be used when the companion term is ‘Hide’:
• “Depending on the nature of a particular group, the Member can choose to hide their email address”.
• Display – is an alternate that can be used when it sounds better than ‘list’, ‘view’ or ‘show’.
• “Upon completion, a success message displays on the results page”.

Preferred Nouns

• Member Permissions / Privileges (select one)
• Emails (remove use of this word?)/ Messages (class of email created by a member and stored on the server - examples include comment and task) / Comments / Notifications (generated by PageSeeder server and never stored). Some glossary entries mention that “a message appears under the editor whenever a draft is saved”

•  “System” should not be used by itself. For example, use “File System.” Instead of ‘System’ use ‘PageSeeder Server’ or ‘Publish Server’.
• Cross References / Reverse Links / Cross references are often referred to as links. PageSeeder displays it as “referenced by”.
•  Search / Omnibox.
• Version – should not be used as a verb. “Increment version” is correct. 
• The public.
• Labels – class of label (explain class).
•  Document Fragments / Sections.
•  Editing / Update.
•  PageSeeder artifacts.
•  Register to become a member.
• Document Modelling - should some of these definitions be in the style guide or glossary?
• Identifier vs ID.
•  Publish, Publish Action, Publish Engine, Publish Engine API, Publish Script, Publish Task.
•  “Scheduled Tasks” – should this use another word instead of ‘Task’ ?

Notes and warnings

Use the appropriate para label for notes and warnings.

Code samples

Code samples should always be in preformated text.

The Website automatically picks which language is used and highlights the syntax automatically.

Console/shell scripts

Commands to be entered on the command line or in a shell script should be prefixed by a ‘$’ for example:

$ yum install pageseeder