The Detail Department

You are here: Home / confluence / Confluence is not a Word Document

Confluence is not a Word Document

by

You’ve just installed a shiny new Confluence set-up for your organisation, now where do you start with writing content for it? Here are my thoughts on writing for Confluence and a few tips and links to help get you started.

My two main points for writing content for Confluence are:

  • Confluence is not a Word document, and
  • Confluence is not a file share.

Despite the advances in the Rich Text Editor in Confluence 4, which makes Confluence much easier to edit and more like familiar tools to make it more like Word, don’t try to make Confluence look and feel like a Word document.

Word documents are a tool to create printed documents, and therefore they have the following features:

  • Page properties – Paper size, margins, page orientation, page numbers, page breaks
  • File properties – File Name, file size, file location, file type
  • Document properties – title page, author details, versioning details,

When these constraints are removed by placing the content in a Wiki, what is left is the content and the formatting – and this is where the focus can be placed to get the message across.

Content Structure

Word documents, especially policies and procedures, can tend to be hefty tomes of seemingly important information that readers have to wade through in order to find the one piece of information they need (eg an employee induction manual may contain one paragraph on how to apply for leave). A table of contents helps to find content within a word document, and so does the document’s search function, but how do they know which document that important information is in, and where to find that document on the corporate file share.

Use the page hierarchy in Confluence to create content that is logically structured and contains discrete chunks of information. Eg Applying for Leave can be a child page of the Leave Entitlements page which is a child page of the Employee Induction page.

If someone is looking for information on Applying for leave, they can search for that phrase in Confluence and it will take them directly to the relevant page. The user will then also have the context of where that page exists in the overall policy by seeing where it exists in the page hierarchy. (using the Confluence Documentation Theme really helps for this). Alternatively the user can use the hierarchy navigation to find the page in the navigation pane.

Each of these discrete pages can contain links to other pages that are relevant to that page. Eg in the for Applying for Leave page there should be a link to the page that tells the user how to find out how much leave they have owing, and a link to the page to list out the different types of leave available. These links may be in different policies or different sections of Confluence, but it is then easy to jump to the right information.

The page titles in Confluence are similar to the headings in Word and they can be named to be relevant to the audience reading the document rather than some arcane naming structure that is currently used in the organisation’s file share.  Eg, Leave Entitlements rather than something like POL123X – Leave Entitlements Policy Version 4.6 Jan-2012 – JG Version (Draft).docx (and don’t tell me you don’t have many files in your organisation’s G: drive that are named like that).

Controlled Documents

If the policy is a controlled document the controlled document code number can form part of the name for the main page (eg POL123X: Leave Entitlements) or by including the policy number and other required document control fields in a Panel on the main page of the policy.

There is a great post on Using a Wiki for Document Control that will help answer some of the specific questions on document versioning and maintenance using a Wiki. These tips are relevant to Confluence also. The important part of this post is how to deal with document revisions.

Do you naturally assume that: (1) the change may be worse than the original document; or (2) the change is probably an improvement over the original? Your answer will have a profound effect on the evolution of every document in your system and on the system itself… Most systems implicitly assume that changes can be dangerous… we decided to make the opposite assumption: that any new version of a document would be an improvement over its predecessor… even an imperfect draft document is better than no document at all.

Another post that will be helpful is Common Sense Steps to Creating a Quality Controlled Document – this is a great resource for remembering what it’s all about – why the document is being created in the first place. I don’t agree with the numbering of headings as they are difficult to accomplish in Confluence, but the other suggestions are useful.

Formatting

Look at the toolbar in Confluence compared with the Ribbon in Word – there are far fewer options in Confluence, and this is a good thing.

When the focus on the content, and not on how the document is going to appear on the printed page, the formatting can be simplified. Word has Styles to build up complex formatting combinations and then apply them with one click or one keyboard shortcut, plus the format can be controlled to a much greater degree by using line spacing, letter spacing, indents etc. Confluence doesn’t have any of those options without doing custom theming and styling, so just work with the options that Confluence provides. “Less is More” in this case.

My tip is that if the content can’t be expressed without resorting to fancy formatting, then it needs to be simplified to be in Confluence. Try to use only the following formatting options:

Other Confluence formatting options to use in a limited way:

Never use:

  • Coloured text – unless it has meaning within the sentence.
  • Underlines – it will confuse people with it being a clickable hyperlink.
  • Any other formatting that needs more than one click to apply (eg Bold + Italics).

Applying fancy formatting to Confluence content is just making it more difficult for you to create, difficult for users to edit if they don’t know your “rules” and difficult  to maintain in the future. Keep it simple and let the content and information shine through.

Using Confluence as a File Share

There are good reasons to add attachments to Confluence, and there are some great attachment handling options in Confluence plus attachment plugins that help managing attachments. The great thing about Confluence is attachment content is searchable within Confluence; but please don’t take that to mean you can just upload your policy documents as attachments to a Confluence page and call it an Intranet.

The idea of Confluence is that all the text is within Confluence and linked to other relevant content and discoverable by clicking just a few links (not hidden away in documents). Confluence content is there on the screen next to a big “Edit” button. Allow and encourage the users to take ownership of the content and edit it as is needed.

The documents that are useful to be attached to a Confluence page are those that must be in a specific format (eg PDF). Excel spreadsheets may be needed to an attachment but then use the {excel} macro to show the content on the Confluence page if possible.  If Visio diagrams are needed to show on the page, then also upload the actual Visio file to Confluence – the Visio file can not be displayed within Confluence (easily), but use Confluence as the place to find the Visio file to edit the diagram. (or alternatively use a diagramming tool that is built into Confluence).

The biggest tip I can give for adding attachments to Confluence is do not duplicate the documents on the file share. Using the “one thing in one place, once” rule, if a document is required to be attached to a confluence page then that is where it lives. Do not keep duplicates or drafts or old versions on the file share somewhere. (Of course, the Confluence content must be backed as much as file share is).

In summary:

  • Keep Confluence content simple, structured, with no fancy formatting.
  • Allow people to take ownership of the content and edit it as they need to.
  • Only add attachments to Confluence if the content can’t be in the Confluence page.
  • Don’t fight Confluence – if it doesn’t do what you want effortlessly and without an expensive plugin, then change the definition of what you want.
  • Also read my post on reusing content in Confluence to avoid duplicating content in Confluence.

Comments