Documentation Style Guide

This document provides a general overview of the style of the it.divinity.edu.au content and is in no ways exhaustive. If you are unsure and need further guidance, see the Google developer documentation style guide, the University of Divinity Style Guide or The Chicago Manual of Style Online (Library Hub login required).

Types of Documentation

University of Divinity documentation is categorised as either Training, Guides or Documentation. These are defined as:

Documentation

Documentation is specific to a particular application and task or concept such as resetting a password, adding a profile picture or how internet links should be used.

Documentation should be aim to be atomic (a singular part of a whole) with the intent that it would be referenced in response to a specific problem or inquiry. If an application sends someone to a support document, it should assist them with the task they were attempting in that application.

Documentation is by nature static, unidirectional in engagement and available at any time without a deadline or completion requirement. A user might access the same document multiple times to recall or diagnose different problems.

Guides

Guides can be thought of as sequenced documentation which connect a series of atomic tasks as part of a larger whole. For example, the ARK: Signalling with Text and Media Areas applies multimedia design theory to the technical processes of adding a series of different types of resources to a section on the Learning Management System. As such it is in multiple parts and regularly sends users to specific documentation on steps.

Guides are intended to help users navigate through a series of concepts or provided collated upskilling on a series of tasks. They might be produced as a result of in situ training such as a Teaching Conference presentation but they will not require completion or have an associated assessment.

Training

Training refers to skill or knowledge development that requires completion and includes assessment. Training might be used for orientation/induction to policies and expectations (e.g. Code of Conduct) or professional development to a specific role or function (e.g. course adviser).

Assessment might be automated (such as an ARK quiz) or be conducted separately by an examiner(s). The training might be entirely online or hybrid with an in-person or Zoom session.

Location of Documentation

Documentation and guides on University IT applications should be hosted on this site (it.divinity.edu.au). At this stage, this site is focussed on documentation in the domain of the University IT department.

Documentation taxonomy

This site has 5 top level documentation folder trees:

• Getting Started
• Cybersecurity
• Student Docs
• Staff Docs
• Projects

Getting Started is accessible from the home page while the other trees are accessible from the top navigation.

Staff Documentation Structure

Staff documentation is grouped by IT application, these are all listed on Getting Started - University Systems.

Outside of this structure is a Getting Started folder and a Guides folder.

Student Documentation Structure

As per Staff Documentation but mostly centred around ARK with a reference page to other University student guides on other websites.

Format of Documents

Page Info Scope notice

Documents should begin with a Page Information notice ( {{% pageinfo %}} ) that scopes the purpose and intended audience of the document. Provide direction to other pages if application might be confused or external references are needed. For example:

For assistance with inserting Page Info notices, see the Code Cheat Sheet

Heading and content structure

Write in a linear progression through a process. Follow the inverse pyramid structure of importance, placing important information at the top of the document and assuming readers will skim the document.

If users may understand the process and just need a quick primer on a key step, you can provide a summary or internal link. A key example of this is the prominent Reset your SSO Password button at the top of the Login Guide. During a stage of major process change, a prominent notice might be required. For example, after the December 2023 ARK upgrade, this notice was placed on the Login Guide:

The pages should follow a linear progression from <h1> (markdown: #) to <h6> (markdown: ######), beginning with <h2> (the page title is <h1>). This is explained in the Presenting Information document. If a section of a document might need direct referencing (either internally within the page or from another document), it should have its own heading. For example, the link to Presenting Information earlier in this paragraph, has a direct link to the heading Headings and paragraphs, achieved by appending #headings-and-paragraphs to the end of the link.

For information on formatting documents for this site, see the Markdown reference.

Process diagrams

For workflows or processes, a flowchart may help illustrate the sequence of events or decision making points. For example (from New Publications):

flowchart LR
    style id1 fill:#ffffff,stroke:#413e39,stroke-width:2px
    style id1b fill:#ffebec,stroke:#413e39,stroke-width:2px
    style id2 fill:#f7f3ec,stroke:#413e39,stroke-width:2px
    style id3 fill:#ece5d5,stroke:#413e39,stroke-width:2px
    style id3b fill:#b79754,stroke:#413e39,stroke-width:2px
    style id4 fill:#740005,stroke:#413e39,stroke-width:2px,color:#ffffff;
    style id5 fill:#a00021,stroke:#413e39,stroke-width:2px,color:#ffffff;

    id1>Item Details]
    id1b>Authorship]
    id2>Publication]
    id3>Classification]
    id3b>ANZSRC]
    id4>Upload]
    id5>Submit]
    
    id1 --- id1b --- id2 --- id3 --- id3b --- id4 --- id5

Diagrams should not be used as the only way to convey information and the information should be clearly indicated in other ways in the document.

See the Code Cheat Sheet for the code for an example Mermaid flowchart.

Working with Policy and Sources

Where a workflow or process is governed by policy, the policy should be clearly referenced and pointed to as the authoritative source. If policy is unclear, do not extend the policy in documentation.

As clearly as possible, refer users to the relevant policy or policy guidance on the University website. For example:

Note: This page documents how to use the extension request form. Students are advised to check their eligibility for an extension on the Grading and Assessment page and the Assessment Policy before completing the form.

If you are unclear about your eligibility for an extension, contact your lecturer or the Academic Dean at your college.