Confluence Wiki

– Shelpa Kaul

Confluence is an enterprise wiki and is developed and marketed by Atlassian Software Systems.
Confluence is used for documentation by code developers and project teams starting from requirement gathering and use cases to deployment and support documentation. Also, software developers use Confluence to document the systems and guidelines.
Technical leads and project managers document best practices, scope, schedule & timelines, status, and risks related to project deliverables.

Confluence Features

Confluence is self-generated, flexible and easy to use. It is helpful in storing and collaborating information, particularly useful in an international workplace. You can edit in two modes: Rich Text and Wiki Markup. Using Rich Text is quite easy as you write in WYSIWYG (what you see is what you get). Power users can author content using Wiki Markup option.

Every aspect in Confluence can be customized; for example, you can customize the interface that includes layout, fields, navigation and colors. Also, you can use the admin preferences to select privileges and security levels.

Confluence bundles up most of the demands required by organizations and enterprises. Confluence integrates features that are perfectly suitable for multiple groups and users. It is impregnable, so confidential information remains secured. With its full-proof permission capability, you can decide who should view and edit content in a particular page, who can have access to the entire space, who can create or remove attachments and comments.

1. Confluence Wiki is not complicated as the other content management systems (CMS).
2. Every user gets to contribute or comment about a topic or on a piece of content. In this way, Confluence helps flow of communication in the team and people who are not authorized to view or edit the content can be eliminated.
3. Information on Confluence is not static; it keeps changing as and when there is a new update in the project documentation.
4. There is an option to view changes made by the users and also restore the versions, so you do not have to fear about losing information.
5. Confluence Wiki can be a repository of knowledge and documentation that develops with your growing project and organization.

Confluence Benefits

• Easy and powerful authoring tool
• Solid attachment feature
• Search is quick and in one specific location and page
• Page history can be tracked and reverting to previous version is possible
• Subscribe to Notification updates (specific to a page or entire space)
• Permission can be restricted for any page
• Content architecture – table of content, left hand or top bar navigation
• Importing excel sheet (file) is possible

User Generated Content (UGC)

Confluence is a classic example of User Generated Content (UGC), as it is mainly generated by the end users who use the content and also keep adding more content to the space.
• Mostly, the content creation is by subject matter experts and also by a technical writer in assistance with a subject matter expert.
• UGC needs to be reviewed and edited by space administrators and technical writers to avoid any wrongly placed content, language and grammar, or to make sure there are no copyright issues.
• In short, the content has be monitored and checked to ensure it meets the set standards.
• Only the project team gets permission/access to the project space. Others cannot view the project name in their Confluence Dashboard. So, the generated content can only be from the project team.
• Comparing with Online help generated using Robohelp, where one needs to install Robohelp to use the tool and update/author content. Here in Confluence, anyone who has access to the project space can update content.
• UGC in a particular project is not open to others outside the project, so there are very few concerns like copying, copyright issues. (This is in comparison to the public sites like Flickr, Wikipedia and others).
• The quality of UGC is sometimes not up to the mark when compared to the quality of documents authored by a technical/content writer. This issue needs to be corrected on regular basis to maintain project documentation standards.

Design Guidelines for Confluence-Wiki

1. Layout and navigation of content
To place the content/information according to their importance and priority, follow Jakob Nielsen’s usability theory that states that users read in the format of ‘F’ 1, 2, 3.

2. Maintain consistency and avoid cluttered appearance
Maintain consistency in navigation and look & feel of all the project spaces.
Leave considerable white space in-between the text columns. There should be good balance between volume of information and white space.

3. Minimize page scroll, almost zero scroll
Research states that only 10% users scroll beyond the first screen.

4. Tooltip for hyperlinks
This gives information to the user about content available on the next screen. These are “trigger-words” that will help the user achieve his/her goal.

5. Pop-up Windows
It allows user to view content in a new browser window. User does not lose the main page and this ensures navigation without any confusion.

6. Tabs Layout and Content Architecture
Tabs feature provides the following advantages:
• More content space for each section
• Helps user navigate the content seamlessly
Content Architecture – Categorize and modify for better content layout, understanding and readability.

Dos and Don’ts to consider as you build your Confluence space

Do
• Keep your space simple and to the point. Let two key words guide you – Categorize, Organize.
• Keep your writing clean, crisp and up-to-date. Readers will keep returning to your space.
• Keep your space uncluttered, too much information overloading keeps the readers away. Should have good balance of information and white space.
• Provide a well-structured content format that is easy and user-friendly to navigate and encourages readability.
• Use descriptive tooltips for the links to make navigation quicker and easier.
• Spell check and proofread the content in your space before publishing.
• Define acronyms and abbreviations when used for the first time.
• Show “what’s new” or “latest additions” in your space.
• Use pre-defined templates for your content. These will help you not only maintain look and feel consistency but also provide cues on the type of information you need to provide.
• Provide references to ideas or content that you have borrowed from other sources, like an article published on a website or in a book.

DON’T

• Make the readers work at finding things within your project space.
• Have too many levels of links. Not more than two or three.
• Have pages to be scrolled. Avoid scrolling as much as possible.
• Use too many graphics that take time to load.
• Use upper case text extensively.
• Write sentences in passive voice.
• Copy or use content or icons created by others without their explicit permission.

Useful Confluence Macros

Confluence macros automate a task that you need to perform frequently or on a regular basis. Tasks performed by the below mentioned macros helps users save time substantially by executing the macro instead of manually duplicating the instructions. These macros are very useful in presenting and arranging content in Confluence.

A few of them are:
1. {card} and {deck} macro – These two macros when used in combination, creates a tabbed panel which is useful in separating content and viewing different topics in the same page at one mouse click.
2. {include} macro – Includes one page within another.
3. {link-window} macro – Links to a page or URL,  that opens in a new window.
4. {align} macro – Allows you to quickly and easily set the alignment of content.
5. {noformat} macro – Used to display unformatted text on your page.
6. {column} macro – Allows you to divide the entire space into columns to manage data representation and better content architecture.
7. {section} macro – When used in conjunction with the {column} macro, helps you to create multi-column layouts.
8. {expand} macro – Used to show and hide blocks of content.
9. {toc-zone} macro – Displays table of content that depends on headings present in the page.
10. {iframe} macro – Displays a webpage within a page.
11. {anchor} macro– Creates a bookmark anchor inside the page.
12. {chart} macro – Displays a chart using data from the available table.
13. {gallery} macro – Creates a gallery of thumbnails of all the available images attached to a particular page.
14. {lozenge} macro – Inserts a graphical panel that is ideal for creating buttons and helpful in systematic representation.
15. {panel} macro – Blocks chunk of content within a panel that can be customized with color and title.
16. {rate} macro – Allows you to rate the space.

Subscribe to Daily Notification

Repeatedly checking the Confluence space to find out if there is any new or updated content can be very cumbersome.
• There is an option that will give you an update on the Confluence content changes that have unpredictable schedule.
• You will be notified through an email every midnight about the entire previous day’s changes made on the Confluence space.

Follow these steps to receive notifications on a daily basis from all the spaces you have access to:
1. Click the Preferences link on the top right corner.
2. Click the Edit Profile tab.
3. Click the Email link in the Preferences box on the menu on the left side.
4. Select the Subscribe to daily updates checkbox and click Save.

About the author:
Shelpa has 4 years of experience in the field of technical writing with Infosys Technologies Limited as a Senior Content Lead. She is zealous about contributing to her field through knowledge sharing and innovation.

About the illustration:
The image is used with permission from Mallika Yelandur.