This page contains notes concerning the global appearance of Confluence, templates, and generally administration guidelines for appearance, campus-wide. it is not open to anyone outside User Services and OLI/FacTS. The purpose is to create a set of guidelines for creating Confluence content that can be the basis for campus-wide use, tutorials, workshops, and so forth.
ITS pages should model these practices as far as possible.
We want campus users to generally follow these standards because:
- Continuity means it is much easier for us to troubleshoot problems for them.
- We can ensure that the macros and arrangements they use will look good on a variety of screens: desktop, notebook, tablet, phone, and so on.
On the other hand, we should be careful not to insist users stick to a narrow list of tools, options, and content arrangements, because:
- We are selling the internet as a diverse, flexible and versatile way of conveying content and promoting engagement. Telling people they must follow a strict style guide offers them much less incentive to bother with it. (Simply touting the efficiencies of paperless communication has a poor record for on-boarding ordinary users to digital technology.)
- We will need to police this, occasionally telling people they "must" change their sites, and "must not" deviate. The more of these kinds of conversations that happen, the more disaffection we can anticipate among users.
I suggest:
- offer tutorial content showing the basics of building attractive content: technical as well as design considerations: follow these standards, and your content is effective. You don't need spend time learning more.
- develop a series of videos showing how to use the basic features to build content. In one-on-one sessions or workshops these are the features we demonstrate.
- indicate that other, "more advanced" features are available, but should only be used with a thorough commitment to testing (time and effort). We can assist with this process.
Developing a best-practice stylesheet will require testing to ensure consistency and reliability of macros, markup, or content arrangement. Below are various features we should consider:
Themes
Currently (5.8) we have only two available, and they are similar. Purchased themese are expensive (up to $2500). We can install a theme builder, but this may bring additional complications and compatibility issues. If we upgrade to Confluence 6, our themes created may need to be rebuilt.
The trouble with the current available themes is that they have a sidebar visible on desktop only. This can provide a table of contents for a space, but that TOC must be duplicated in the body of the page, because it (or the child pages list at the bottom of the desktop page) is not visible in Confluence Mobile.
Tools Available to Users
Headings
Headings are easy to explain. The Table of Contents Macro is easy to explain, and uses headings.
Panels
Panels are easy(ish) to explain, and produce callouts that are brightly colored (unlike tables, which are limited to pastels).
Tables
Tables as standard form of organization, especially for tutorials. Recommended.
Testing:
- Android: Chrome browser. Tables usable. Look OK.
Columns
Several ways to use columns. They aren't necessarily difficult to construct, but they complicate views on various devices. I see this as an advanced feature, not recommended for most users.
Macros
Page Tree. Simply lists pages in space. I strongly recommend this for the home page for each space. Indeed, we might make it the only allowable editable content on each space's home page, other than perhaps a welcome message. We should have this despite a page tree existing in teh sidebar and the "child pages" list below, because those are not visible in mobile. Those who create content and maintain pages in the Canisius College wiki should follow a consistent set of guidelines for organization and page style. Visitors - students, faculty, staff, and outside clients - should encounter a consistent experience wherever they are in the wiki. For example, if you neglect to add menus, use headings, follow good practices for linking file attachments, and removing out of date content, your intended visitors may fail to find, or worse, find the wrong information in your wiki pages.
Happily, the tools and practices described below are simple and easy to follow.
| Table of Contents |
|---|
Tools Available to Users
Headings
Headings are pre-defined styles of text common across word processing and web development applications. Employ headings for the titles of sections, to create a nested outline of topics.
- In Confluence, headings help users identify different sections (and subjects) clearly. Then, using the Table of Contents Macro, you can rapidly create a self-updating, hyperlinked table of contents on a page. This page has a good example of this.
- In most other applications, headings do the same things. For example, try them in Microsoft Word, where you can also install an automated table of contents.
- In all places, headings are used by technologies for the visually impaired, and so are essential for accessibility.
Headings should be used sequentially (Heading 1, Heading 2, Heading 3, and so on.) Start with Heading 1, and don't skip heading styles as you build your outline. You can see an example of headings, and how they interact with a automated Table of Contents builder called a macro, here.
See this tutorial video for how to Install Headings and the Table of Contents Macro, for ideal page organization.
Tables
A simple element available in the main page editor toolbar are tables. These can help organize information better than simple paragraph text, and are easy to install.
Click Table icon in the toolbar, and the wiki prompts you to choose how many cells you would like. You can add or remove rows and columns later. By default, the wiki highlights a header row, but you can avoid that by holding down the shift key when you select your cells.
Once you install a table, Confluence provides another toolbar level with tools specifically for tables. You can activate this toolbar at any time in the page editor, by clicking within a table cell.
You can experiment with the various table options, to see how they work. A nice accent is to select each cell, row, or column, and use the color picker menu (second from the right) to choose various pastel colors. Obviously, Blue and Yellow are appropriate!
Another helpful tip: you can use a single Table cell just to act as a highlight box for particularly important text. For example:
| Your Readers are more likely to notice this, because it is in a single table cell. |
|---|
Macros
We recommend two macros for use across the wiki.
Table of Contents
The Table of Contents Macro lists text formatted in Heading Styles, in numerical, nested order, on pages. It is configurable, but even the default macro will improve any lengthy page. Here's an example:
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
You can see how the Table of Contents macro interacts with headings in more detail, here.
See this tutorial video for how to Install Headings and the Table of Contents Macro, for ideal page organization.
Children Display
Lists any child pages of the pages on which it is posted. Recommended the home page for each space, as well as parent pages for offices. "Page Tree" purports to do the same thing, and we used it in the past, but it is not visible in the mobile browser version, so it should be replaced. Here's an example of child pages listed by this macro:
| Child pages (Children Display) |
|---|
Tutorial Video Adding Navigation to your Confluence Pages
| ||||
00:00 Do Not Rely on the SideBar Menu 01:21 Children Display Macro 03:49 Adding Internal Links Manually 06:38 Add "Back" Links to Wiki Pages |
Verify that these two work on mobile.
Horizontal Rule
Although not essential, you can install simple lines between paragraphs or headings that help set apart different subjects or topics. There's examples above. Here's another:
...