Documentation site

• 1: Documentation Style Guide
• 2: Code Cheat Sheet

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

2 - Code Cheat Sheet

Alert shortcode

Alert shortcode is used for essential information or tips. Essential information should be in the primary colour and tips short be in the secondary colour.

Parameters

• title - free text title
• color - stylesheet defined colour name. primary is #b10024 and secondary is #a48545.
• alert text - free text placed inside the alert tags

{{% alert title="title goes here" color="colour goes here" %}}

Insert your alert text here

{{% /alert %}}

Example Shortcode

{{% alert title="Example alert shortcode" color="primary" %}}

This is an example alert shortcode. Colours defined in the site are ```"primary"``` (brand red #b10024) and ```"secondary"``` (brand gold #a48545).

{{% /alert %}}

Example Output

Imgproc shortcode

See Docsy Doc: imgproc shortcode

Add screenshots and other images using the imgproc shortcode. The shortcode will resize the image for you and place it inside a figure tag with a border to display neatly on the page.

The imgproc shortcode takes an image in the page bundle (basically the folder in which the document is located - see Docsy docs: Page bundles) and resizes it on page build based on the specified processing parameters. The Fit process is the only process in common use.

To add a screenshot using the imgproc shortcode:

1. Take a screenshot and place it in the same folder as the markdown page. The folder structure followed on this site is to create a folder with the name of the document and a single page index.md (see Hugo docs: Single page templates). This structure is followed for ease of site maintenance.
2. Name the screenshot a unique name. A semantic naming convention followed on most docs is: staff/student-docs + application + document name + interface element + action. A unique name is necessary to ensure that the shortcode processes the correct image.
3. Insert the imgproc shortcode, placing the filename in the first position.
4. Set the dimensions inside the third position.
5. As appropriate, add a caption between the open and close tags of the shortcode.

Parameters

• filename - unambiguous name of the image in the same page bundle as the document
• process - usually Fit. Could be Resize, Fill or Crop
• processing options - for fit width in pixels and height in pixels separated by “x” (e.g. 250x250)
• Image Caption - note: if annotating (see Annotate images), make sure this doesn’t move your annotations on different viewports

{{% imgproc “filename” Fit “processing options” %}}

image caption

{{% /imgproc %}}

Debug tip

Incorrect or ambiguous image names are a frequent cause of Hugo server errors. Following the staff/student-docs + application + document name + interface element naming convention strictly will help avoid these errors.

Example Shortcode

{{% imgproc "docs-site-code-cheat-sheet-example-imgproc" Fit "450x450" %}}

This is a sample code for an imgproc shortcode with caption. (Note that the pictured example shows syntax markup in VSCode).

{{% /imgproc %}}

Example Output

Page info shortcode

{{% pageinfo %}}

**Insert info text here**

{{% /pageinfo %}}

Example shortcode

{{% pageinfo %}}

This is a page info box.

{{% /pageinfo %}}

Example output

Youtube shortcode

{{< card header="$1" >}}

{{< youtube id="$2" title="$1" >}}

{{< /card >}}

Mermaid

The Mermaid diagramming and charting tool is installed on this site. For a guide to using Mermaid see the Mermaid Doc: Getting Started.

Mermaid flowchart

    ```mermaid
    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>$1]
        id2>$2]
        id3>$3]
        id4>$4]
        id5>$5]

        id1 --- id2 --- id3 --- id4 --- id5
    ```

HTML elements

Icon tables

Create table in excel with Y, o N. Upload CSV to Markdown Tables Generator. Find and replace with HTML below:

Field required

<i aria-hidden="true"  class="fa-regular fa-circle-check" title="Required field" style="color: #009400;"></i>  

Optional field

<i aria-hidden="true" class="fa-regular fa-circle" style="color: #898379;" title="Optional field"></i>

Field does not exist

<i aria-hidden="true" class="fa-regular fa-circle-xmark" style="color: #d10000" title="Field Does Not Exist"></i> 

Annotate images

Outer HTML

<div class="position-relative" style="max-width:1000px;">

</div>
<p>

Tippys

Change the following as required:

• href
• bg-primary or bg-secondary
• style left and top position
• data tippy content

<!-- Marker 1a: Section Description -->
<a href="#presentation-resources" class="screenshot-marker lh-1 fw-medium text-white position-absolute transform-center px-2 py-1 bg-primary rounded-circle" style="left: 26%; top: 1.5%" data-tippy-content="Section Description" aria-expanded="false">1</a>