The PageSeeder Style Guide

The purpose of the PageSeeder style guide is to maintain a consistent writing style across PagaeSeeder documents

ConventionUse
Bold
  • PageSeeder commands or instructions such as "click on", "edit" or "publish".
Italics
  •  Official PageSeeder names such as "Publish Engine".
  • Non PageSeeder terms or names such as "Wikipedia" or "Java".
  • Commands that are external to PageSeeder like "directory listing", "whois", "ipconfig." .
Code (monospace text)
  •  File or folder names "template". 
  • Programming or configuration code.
  • User input. 
Capital Letters
  • Organization names "Apache" or names of people "Ted Nelson". 
  • Names of software applications  "Tomcat".
 Glossary

The purpose of the Glossary is twofold:

  • to disambiguate terms that may have alternate meanings to their use in PageSeeder (document: use PageSeeder document or non-PageSeeder document).  
  • to direct users to additional information similar to a traditional book index.
    eg. Group: an object that acts as a container for members or content. See also Create a Group, Add a Member etc

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

Rules 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.

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.

Rule No. 1: Use capital letters to begin proper nouns, sentences, headings, some abbreviations and acronyms, and the important words in composition titles. Proper nouns are the particular names of people, places and things. Rule No. 2: Do not capitalize the first letter of a word (or words in a phrase) simply to highlight it or because you or someone else think it's an important word. Excessive, arbitrary capitalization distracts the reader and hinders reading.

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 endash character '–' (alt+0150).

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

Headers

H1

H2

H3

H4

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 will help 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 may 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 will display on the results page"

Preferred Nouns

  •  "System" should not be used by itself. For example, use "File System." Instead of 'System' use 'PageSeeder Server' or 'Publish Server'.
  • Version - should not be used as a verb. "Increment version" is correct. 
  • The public
  • Labels - class of label (explain class)
  •  Editing / Update
  •  Register to become a member.. Maybe register should only be used when referring to groups?
  •  Standard Format / PS Standard
  • 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' ?

Headings

Use title case for headings and document titles. Title case capitalizes the first letter of the first, last, and all significant words.

Verbs

Verb tense and mood preferences, with examples:

  • Avoid the first person. For example do not say, “We will begin the backup process by locking the database,” or “I begin the backup process by locking my database instance.”
  • Use the second person. “If you need to back up your database, start by locking the database first.” In practice, however, it’s more concise to imply second person using the imperative, as in “Before initiating a backup, lock the database.”
  • When indicated, use the imperative mood. For example: “Backup your databases often” and “To prevent data loss, back up your databases.”
  • The future perfect is also useful in some cases. For example, “Creating disk snapshots without locking the database will lead to an invalid state.”
  • Avoid helper verbs, as possible, to increase clarity and concision. For example, attempt to avoid “this does foo” and “this will do foo” when possible. Use “does foo” over “will do foo” in situations where “this foos” is unacceptable.

Referencing

  • For non-object references (i.e. functions, operators, methods, database commands, settings) always reference only the first occurrence of the reference in a fragment. You should always reference objects, except in headings.

  • Structure references with the why first; the link second.

    For example, instead of this:

    Use the How do I create a task? help page if you have a problem creating a task.

    Type this:

    To create a task, see the How do I create a task? help page.

Jargon and Common Terms

Preferred TermConceptDispreferred AlternativesNotes

document

Prefer document over ________
project
omniboxsearch

Created on , last edited on