This article is obsolete

The content on this page was incorporated into the Content Development Guide on 28 August 2024 and is now OBSOLETE.

General

When inserting links or references, have the text of the link be significant (also avoid links that say "click here"), for example [incorporated]
- preferred form: :ref:`create a new authorized value category <add-new-authorized-value-category-label>`
- non-preferred form: :ref:`create <add-new-authorized-value-category-label>` a new authorized value category
Use American English [incorporated]
Write 'system preference' in long form (rather than just 'preference') [already incorporated into the Terminology list]
Use 2nd person (you do this and that) [incorporated]

Screenshots [incorporated into the structures and guidelines section]

Try to take general screenshots that can be reused in many places, for example, I will take a screenshot of all options in a menu rather than very specific screenshots of a single button/option

Classify the screenshots in the module where they were taken rather than where the screenshot is used in the manual, for example, a screenshot of an OPAC message in the OPAC will be classified in the OPAC directory even if it is used in the patrons chapter to show how it looks to the patron when you add a message in their file

Use verbs and present participle, for example
- preferred form: Adding an authorized value
- non-preferred form: Add an authorized value
- non-preferred form: Creation of an authorized value
Always add a label, so that this section can be referred to elsewhere

When describing a form, use a bullet list and each bullet should start with the label of the field, for example
- preferred form: Name: this is the name of the field as you want it to appear.
- non-preferred form: Enter the name as you want it to appear.
- non-preferred form: Enter the 'Name' as you want it to appear.

Cut lines at 80 characters if possible (not always possible, esp. with tables) [incorporated into the source file formatting section]
Do not cut ref links (it creates errors or warnings upon build) [incorporated into the source file formatting section]
Follow bullet points with two spaces [incorporated into the source file formatting section]
End complete sentences with a period [incorporated into the punctuation section]
Use single quotes, except if the content has an apostrophe [incorporated into the punctuation section, was already partially covered]
Use single quotes and capitalization for button names, for example [incorporated into the conventions for interface elements section]
- preferred form: Click the 'Submit' button.
- non-preferred form: Click the submit button.

How to indicate modules (capitalized or not? in single/double quotes? In italics or bold?) [incorporated into conventions section, with a TO DECIDE indicator]
Tense of verbs in sentences [incorporated into the active vs passive section, with a TO DECIDE indicator]
- Present: the number of holds is displayed; the button is on the right
- Future: the number of holds will be displayed; you will see the button on the right