Standards and conventions

The documentation area of the site follows a number of conventions.

Reader segmentation

We believe there are a number of audience categories that documentation should be written for. These correspond to  different information spaces as well. The categories (in increasing order of need for sophisticated information) are:

• users - for members of the general public
• content creators - for people who need to create content
• administrators - any administrators of the website, including both website and security administrators
• developers - for power users of Sytadel who wish to modify its configured behaviour

There is also a general documentation information space, used for release notes, installation notes etc. The target audience is adminstrators and developers. Each site will also typically have its own documentation information space(s), according to the degree of customisation involved for the organisation.

Kinds of documentation

We provide different kinds of documentation, made available to the different audience categories. These are mapped onto different information architectures, appropriate to the nature of the documentation and the audience. They are:

• introductions - very high level overviews, targeted to each audience category, as topics
• help - a fairly flat information architecture, using FAQs to answer common questions
• guides - a deeper information architecture broken into audience categories and built around activity-driven descriptions of how to use the system in everyday activities, using topics and FAQs (cross-related to help)
• tutorials - task-oriented descriptions of common activities, broken into audience categories and mapping to the high level activity descriptions of the guides, using topics and articles
• reference manuals - detailed and deep information architecture, driven from a technical feature perspective, using topics, articles and files
• glossary - frequently used terms found in the documentation in describing the system and their meanings
• release and installation notes - descriptions of changes to the system and how to install new releases

Language

The language of the documentation is Australian English. The authorative dictionary is the Macquarie Dictionary.

Titles should be descriptive and short, particularly for topics.

Terms from the glossary should be used consistently, and when a term is being used that has a specific Sytadel meaning, it should be added to the glossary if not already present.

When code is written or it is important to talk about a Sytadel content type, it should be written using fixed width font.

1. Short sentences, which begin with a capital letter and be punctuated at the end of the sentence. The first few words of the sentence are important; it should not just repeat the Name/Title of the topic/article. A good example is this sentence.
2. A list of things that the content discusses; this may include the names of subtopics. The list should capitalise the first word and punctuate the end of the list. Items in the list should be separated by semi-colons for logically separate list elements. For example: "FAQs, articles and topics; summaries." and "Templates; page definitions; and option settings.".