SLQ Wiki Contributors Guidelines

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

Audience and Contributors

SLQ Wiki has content that ranges between:

descriptive

instructional

authoritative

speculative.

The spread of audience and contributors ranges from:

internal State Library staff and volunteers

external State Library (not based at South Brisbane)

local and regional librarians

local and regional councils

arts and community workers

educators and students

public workshop participants.

Defining Tone and Style

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 State Library style for Ideas and Planning.

Ideas

This is informal, ad-hoc and just-in-time communication. For quick notes, sketching and note-taking1) 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 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 State Library 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 State Library Style Guide should be followed. This content includes finalised public workshops, pages about the SLQ wiki (like this one) and public talks give by State Library staff.

Applying the State Library Style

The State Library 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 State Library Style Guide effectively covers the tone required for the SLQ Wiki.

Except in formal communication, State Library ’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 State Library’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 State Library 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 State Library'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 State Library Web Style

While the basics of formatting your page are carried out by the Dokuwiki platform, the State Library 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 State Library 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 State Library.

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 State Library’s diverse collection.

Linking

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

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

External Links

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:

Correct: Wikipedia: The Free Encyclopedia

Incorrect: Wikipedia: The Free Encyclopedia

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) intelligent content

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.

Research

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

Hack-a-Day style guide

Instructable Style

How to write an instructable

and

Guidelines for getting featured

MOOC Style

OpenEDx Course Content Generation Guide

Blogging Style

tech blogging style guide

Community Development Style

http://nht.org.au/wp-content/uploads/2015/12/Community-Development-Resource.pdf

Process Documentation Style

Process documentation

Technical Documentation Reference

Analog devices Wiki