SLQ Wiki Style Guide

Background

From December 2017 to July 2018 The Edge program team was commissioned to launch this wiki as a public, open-source platform for community engagement in art, science, technology and enterprise. Doing so not only required implementation of a significant ICT project but also required the organising and focusing of the presentation and content that this platform will support to ensure the project achieves its strategic objectives.

This style guide is intended to cover the tone, style and conventions used when creating or editing content for the SLQ Wiki. Dokuwiki plugins used in the SLQ Wiki are also covered.

SLQ Wiki has content that ranges between:

  • descriptive
  • instructional
  • authoritative
  • speculative.

The spread of audience and contributors ranges from:

  • internal SLQ staff and volunteers
  • external SLQ staff (not based at SLQ South Brisbane)
  • local and regional librarians
  • local and regional councils
  • arts and community workers
  • educators and students
  • public workshop participants.

Defining a style and tone for such a diverse audience is challenging. By nature a wiki can be collaborative, eclectic and experimental which will add diversity of authors and increase complexity. We have based this style guide on State Library's internal style guide, which we have supplemented with research into external online style guides.

SLQ Wiki Content Types

We've identified three types of SLQ Wiki content. Ideas, Planning, and Releases. Tone and style may diverge from standard SLQ style for Ideas and Planning.

Ideas

This is informal, ad-hoc and just-in-time communication. For quick notes, sketching and note-taking1) and discussion.

Workshop prototypes, where rapid iteration is required due to tight deadlines are a good example of this. Other examples include community engagement programs and Hack The Evening community generated content.

The tone can be informal and will change obviously between authors, whose style will contain personal quirks and relaxed language. Spelling, punctuation and grammar may be compromised for the sake of brevity and speed.

Planning

This covers engagement, product and process development, rationale exposition and broad scale planning. Once again tone can be informal, and will vary between authors - but more complex, academic, or domain specific language can be used. At this point writers should be aware of the SLQ Style guide and should begin to formalise their style in line with this for pages that may be released.

Release

This content is authoritative, polished and proofed. It is based on competent authority and reliable because it is coming from a person who is an expert or properly qualified. The tone will be consistent throughout the work. Technical details will be finalised and up-to-date as required and the correct SLQ Style Guide should be followed. This content includes finalised public workshops, pages about the SLQ wiki (like this one) and public talks give by SLQ staff.

The SLQ Style Guides cover a broad range of communications. We should be applying them for all Release content, and be aware of them for all Planning content.

Tone

The SLQ Style Guide effectively covers the tone required for the SLQ Wiki.

Except in formal communication, SLQ’s tone of voice is informal, clear, direct and friendly, and audience-focussed.

Our brand, all yours, drives all of our communication, meaning that our visitors, library members or anyone engaging with us, or with whom we would like to engage, is at the centre of all of our communications. This is a significant shift in the way we have traditionally spoken to our audiences. It is important we consider all of our communications through the all yours filter.

Considering our audience/s and potential audiences helps to improve communication and to convey SLQ’s key messages effectively. For example:

  • Old : State Library of Queensland provides access to collections.
  • New : You can access collections…

As the SLQ Wiki is informal communication, we use inclusive, second person and third person language.

  • To convey a friendly tone and engage the reader, use the second person ‘you/yours’.
    • Eg: You are welcome to visit the Infozone at any time.
  • To emphasise positive relationships, use ‘you and us’ linking first and second person.
    • Eg: We would love for you to contribute to the Flood and Cyclone Mosaic.
  • To describe SLQ activities from an objective viewpoint, use third person (he, she, him, her, his, hers, they, them, theirs, it). This is also appropriate for formal communications.
    • Eg: One of SLQ’s Indigenous Editors is Ellen van Neerven-Currie. She was also a finalist in the 2012 David Unaipon Award for her first novel.

Applying the SLQ Web Style

While the basics of formatting your page are carried out by the Dokuwiki platform, the SLQ Web Style guide covers the key areas of content formatting that produce high quality conformant content. Once again, if you are working on Releases or Planning you should be aware of the SLQ Web Style.

Page names/titles, web paths, headings and subheadings

General guidelines:

  • use reasonably short titles and headings where possible
  • omit leading articles in titles and headings, to save space
  • do NOT underline text

Page names/titles and web paths (URLs) The title of a web page should be:

  • succinct
  • meaningful
  • relevant to the content
  • different from the titles of the other pages on the website

Remember that page titles are often used out of their original context – in search engine result lists, web paths (URLs), in browser bookmarks/favourites and history lists, and as links on other sites, for example – and must be able to stand on their own.

Page headings and subheadings

Don’t use the same first word in several subheadings on the same page, to avoid visual “sameness.” Eye tracking studies indicate that the left side of the content area of a page gets more eye fixations than other areas. This means that headings should include unique keywords to help people locate what they want as easily as possible.

Capitalisation

Make sure that the first main word in titles, headings and subheadings is capitalised. Don’t capitalise a word such as “the” or “and”, unless it is the first word in the heading. We use sentence case on our various websites.

Numbering and bullets

Avoid using a number series over more than one page. Remember users may be linked to a page anywhere in the wiki. Two styles are used by SLQ.

Style one is used for information delivered in independent sentences or paragraphs that can be more easily understood when bullet pointed. Each bullet point starts with a capital and ends with a full stop.

Eg: The program has several aims:

  • Improving the quality of service provided by public libraries to Queensland communities, especially those experiencing social, economic and geographic disadvantage, is paramount.
  • Supporting the development of new library services in the community, in particular the provision of low cost access to new technologies, is also important.
  • Fostering community development by supporting partnerships between libraries, local businesses and community services will be a focus next year.
  • Raising the profile of public libraries in the community is an ongoing challenge.

Style two is used for information comprising sentence fragments (ie one sentence over the course of the bullet pointed material). The sentence begins with a capital, uses a colon to introduce the list and each bullet item starts in lower case. There is no punctuation at the end of each item, but the last item ends with a full stop.

Eg: SLQ Gallery will:

  • enable diverse groups of clients to view and interact with innovative and creative multimedia presentations
  • present interpretations of Queensland’s and Australia’s unique and diverse history and culture
  • showcase SLQ’s diverse collection.
  • Do not include too many links within a page’s content, as they may detract from the viewing experience
  • Don’t include too few either, as the viewer may feel trapped on the page, with no easy way out
  • The number of links will depend on the content of your web page.

Consider the reason you are providing the links:

  • Do they add value?
  • Are they really necessary?

You may be able to compromise by including a list of useful websites at the end of your page.

Internal links is the key functionality of a wiki, and is covered the in the dokuwiki syntax.

  • When you are linking to an external site, please do not include the following: [new window] after the name of the site.
  • The text used as a link should be meaningful enough to make sense when read out of context. Example:

Do not use phrases such as “click here” or “this link” as links. Not all our potential users can click. Use content-descriptive words instead, e.g. name of the website, organisation, person, file, etc.

Example of good linking: Wikipedia has an article on NAIDOC.

Example of bad linking: Click here to see a article on NAIDOC.

Content Organisation - Tagging or Hierarchical?

We are aspiring to produce 'intelligent content' 2)

Simply put, ‘intelligent content’ is content which is not limited to one purpose, technology or output. It’s content that is structurally rich and semantically aware, and is therefore discoverable, reusable, reconfigurable and adaptable.

Encyclopedia Style

The most comprehensive guide for this style is probably the Wikipedia Manual of Style.

On-line Manual Style

The Dozuki house style guide is an excellent example of best practice.

Hacker Style

Instructable Style

MOOC Style

Blogging Style

Community Development Style

Process Documentation Style

Technical Documentation Reference


1)
whether this is ideal use for a wiki is up for debate, however we tend to err on the side of just getting something down in the moment
Mick Byrne, 2018/02/19 13:06

All the resources above are great Andrei - I guess we probably need to have tags to identify pages (or sections) under different categories of content - (descriptive, instructional and speculative) and then have templates and guideline for each category.

Mick Byrne, 2018/02/19 14:20

Maybe theres tags that could be used for filtering out content for different levels of audience or use (Beginner, intermediate or advanced). This could be a tab type separate from user permissions. There may be a time I want to bring up a basic (facilitator view only) of a session plan when i am delivering a workshop. Other times i'll want to dig deeper to see the commentary or reflections on aspects of this session plan.

Warren, 2018/06/18 13:33
Thanks for the links - these are great resources
Enter your comment:
Y H Q R E
 
  • facilities/slq_wiki/wiki_style_guide.txt
  • Last modified: 2019/03/12 09:19
  • by Andrei Maberley