JIRA and Confluence Upgrade Highlights

Question

Hello,

First off I know that this can be researched in the release notes, however, I am curious for people's opinions:

I am planning an upgrade of both JIRA and Confluence (JIRA is currently on 5.2.11 and Confluence on 3.5.6)

The plan is to bring JIRA up to 6.3.15 and Confluence up to 5.6.6

I am planning a training session post upgrade to go over the highlights of changes and new features and was curious as to what the user community felt are some of the most significant and/or notable changes and new features going up to these versions that would be most helpful to go over in training sessions.  These will be broad training sessions to reach out to our user base as a whole (about 2000 users).

Thanks for any advice/tips!

Neil Taylor · Answer

Thank you everyone for all of the great advice!!

Teresa Hollidge · Answer

Hi Neil,

Our engineering Confluence (3.5.16 > 5.3.4) and JIRA (5.2 > 6.1.7) servers will be upgraded tonight! We upgraded our customer facing Confluence instance about 18 months ago.

I have pasted the info we provide to our engineers below. It's very high level but it touches on most of the points that annoy/confuse our folks. Some of the info may be specific to our environment so YMMV. Aside from the loss of wiki markup, the most frequent question we received after we upgrade our first server was "How do I create a new page?"

Good luck!

Teresa

Getting Started with Confluence 5

The upgrade of Confluence from 3.5 to 5.3 is rather dramatic. If you have experience editing on docs.emeter, the upgrade of wiki.emeter to Confluence 5 will be uneventful because the functionality of both systems will be the same. If you do not have much experience editing on docs.emeter, the following information is provided to help ease your transition. If you have any questions or need any help please contact anyone on the Docs Team for assistance, or send an email to docs.emeter.ic@siemens.com.

The information provided here is intended to be used in conjunction with the existing Writing Technical Documentation.

Major Differences between Confluence 3.5.16 and 5.3.4

No more wiki markup View for editing
 Wiki input is supported, but upon insert, it is automatically converted to the new "rich text" format. Some menus and navigation have changed
 IE limitations - drag-and-drop and cut-and-paste is not fully supported. Use Chrome instead.

Redesigned Toolbar

Dashboard available under venetian blind icon at far left of top bar – Spaces is now on top bar rather than just Dashboard
 Create button replaces Tools > Add dropdown for creating a new page

Browse > Space Operations replaces Tools > Advanced

Notifications icon added (inbox next to user icon)
 User name in top bar replaced with user icon (mouse over icon to see user name)

For Confluence Admins, admin functions move from Browse to a separate Cog icon

Other Display Differences

Save, Cancel and Preview are now buttons at the bottom of the Page
 Draft saved notice is now below the Preview|Save|Cancel buttons (almost hidden). If you don't see it, try resizing your window.
 You can "pin" pull down menus
 Reorder Pages link at bottom of the page is gone.

To reorder pages within a space, use Browse > Space Operations, select the Pages tab and Tree view. Workflow status remains on page header, but workflow actions are now controlled through a separate icon

Hovering your mouse over the workflow state displays the complete workflow process, but as a read-only view

Setting Preferences

By default, Confluence 5 is not including content changes in email notifications about updated page content. To change this setting, and include "diff" style changes in your email notifications:

1. Select Settings from your User icon pulldown menu.
 2. Click on Email.
 3. Click the Edit button at the bottom of the Email Settings. 4. Select "Show changed content" and click Submit.

Wiki Markup to XHTML Source Format

Confluence's switch from wiki markup to an XHTML source format has a few ramifications:

Wiki markup edit view is no longer available
 The enforced structure of XHTML provides more reliable sources – formatting issues introduced by toggling between Rich Test and wiki markup no longer exist

Copying between older systems with wiki markup and the new system requires a slightly different procedure Viewing older (wiki markup) versions of a page is not possible on the new system.

Edit Mode

All editing is in a Word-like editor, similar to the Rich Text editor in Confluence 3.5
 Even those familiar with the Rich Text editor in Confluence 3.5 will notice a few changes. In particular, most macros appear as "containers" with the macros text included within the container and the macro name and parameters shown in the top border of the container.

Adding new pages
 Use Create button instead of Tools > Add.
 Pop-up window prompts you to select the Space for the new page and the type of page to create. Default is to create a child of the current page as a blank page.

At this time, other page formats are not approved. Gliffy diagrams can be created within a page and should

not be created as stand-alone documents.
 Cursor is positioned in body of page, making it easy to skip adding the required page title. You will have to add a title in order to save your new page.

Wiki markup accepted as input
 To insert a macro: just start typing the opening curly bracket and the macro name. You should see macro suggestions based on autocompletion. After selecting suggestion (or typing entire macro name and closing bracket), the macro appears in your document and you can use it.
 To insert bold or italics: type the asterix or underline as desired followed by your text. When you type the closing symbol, the text will automatically be converted to bold/italics and display appropriately (the asterix or underscores no longer exist).
 You may see some content in a container labelled "Wiki Markup". These are legacy issues from the format conversion with custom eMeter macros. They can be edited as they were in the old system, and they appear in the page View as they did in the old system.

Creating lists
 Can insert wiki markup to initiate lists, but once the list is started in the editor, then the list operates as it did in Confluence 3 and wiki markup is taken literally.
 Can insert Bulleted and Numbered lists directly from the toolbar.

Task lists are also available, but we don't use these.
 Use Tabs to nest lists within list items, or use the indent/exdent icons on the toolbar.

This will take some getting used to!

Insert > Other Macros (+ dropdown)
 Launches window showing all available macros. Scroll through alphabetical list to find and select desired macro or use the search bar at the top of the window. If the macro contains text (for example, code) or parameters that can be set (for example, language), a separate window opens, prompting you for these items. Click Insert to return to the edit page with this macro and content added.
 If you want to set an optional parameter, you need to edit the inserted macro (click on the macro and the Edit|Remove options appear below the macro container). Select Edit and set the parameter in the popup window. There is no way to edit the parameters within the edit page directly.
 The Insert > Other Macro dialog stays on the last macro added the next time you open it.
If you click Remove, the entire macro container and all contents are removed. Be sure to move (cut and paste) the contents of the macro outside of the macro container before removing it if you want to preserve them.

Global search and replace (where global = within a page)
 1. Click the search button in the Edit page toolbar (or Ctrl+F for Windows or Cmd+F for MacOS).

A Find/Replace toolbar line appears.
 2. Enter your search term in the Find box displayed. This field is not case-sensitive (for example, entering foo will also find Foo and FOO).

Use the Previous and Next buttons to find occurrences of the term throughout the page.
 Enter a replacement string in the Replace box and click Replace to replace occurrences one at a time or click Replace all to replace all occurrences at once.
 A status window pops-up near the lower right corner. If your string was matched, it displays the number of replacements made. If not, it displays that no replacements were made.

eMeter Custom Macros

Custom eMeter macros appear in the Insert > Other Macros panel: Glossary, PropertySets, and ReleaseNotes Issues.
 Internal Macros

ToDo - this is a free for all for anyone to use to record instructions, ideas, or comments about what needs to be done for that page, or to preserve content you don't want customers to see but want to retain.
 DocsOnly- this is used by the Docs team for notes and planning
 InternalOnly - this is a used for communicating ideas between the docs team and engineering personnel

Parameters:
 User: your name – the person writing the note
 Date: the date the note was added
 If you want to address your comments to someone specific, include their name in the text

Style Macros FigureCaption

TableCaption Example

Copying wiki markup
 Copying old wiki markup into a page open for editing will result in raw wiki markup as content.
 To copy and paste old wiki markup in Confluence 5, choose Insert > Wiki Markup and paste wiki markup inside the box that pops up.Save the content, and it will be converted to the new format and inserted into document for editing.

Viewing the Source Format
 Access to this functionality may be restricted
 This should be used cautiously – there is no validation performed on changes made in the XHTML code! Occasionally this is useful for tricky cursor positioning or validating what you see on the page
 While editing a page, click the source edit icon in the toolbar.
 Source format displayed as a structured, color-coded view of the XHTML source in a separate window. Click Apply to have changes made in this window appear in your edit view.
 The icon for editing the Source Format does not appear until a new page has been saved. The XHTML source is created when the page is written to the database. It can't be edited until it has been created.

Tables

Word-like, graphical table editor for creating/inserting tables Separate table toolbar appears when editing a table
 Now supports cell spanning
 View mode allows sorting of table columns

Can sort on any column heading in View
 Cannot preserve and store sorted output (yet)
 Tables that have spanned columns don't allow sorting on those columns in View

Can apply background color to rows and columns through table toolbar We recommend against using this unless absolutely necessary!

Nested tables are now possible, but they are not formatted in the printed output and should not be used

Inserting Graphic Images

Use Insert > Images to include an existing graphic file (which should be in PNG format) as an attached graphic. No longer need to attach graphic before you can include it.

Use Insert > Gliffy Diagram to create illustrations within your page.
 This is the preferred method as it allows us to store both the source of the image and the final display version with the page.
 The Gliffy "editor" is launched directly from the Confluence edit page.
 You can start with a blank page, or select from previously created Gliffy images.
 When you Save the image, you will be prompted for a filename. Try to provide a unique, descriptive name.
 Click Exit to exit the Gliffy editor and return to your Confluence page.

Use a FigureCaption macro.

If you edit a Gliffy diagram, but do not make any other changes on the page, the page history is unaffected. The graphic changes are not included in the page history and the "last edited" information does not get updated. The revision history of the diagram will show the user, date, and time of the changes.

DOCRESOURCES-GettingStartedwithConfluence5-250215-1739-590.pdf

Mike Rathwell · Answer

Neil,

I suggest you spend some time on the features that are new in the new version of Confluence. There are a TON of them between the 3.5.x and 5.6.x (I'm on 5.7 now, actually) versions. For example, the thing that pushed me to finally get off my butt and upgrade was a personal one; i wanted (needed) to be able to include a page excerpt from a different space; couldn't do it on 3.5. This is a small one but one of many.

The thing I noticed when I did the upgrade over time (quite short) was the contributions to the wiki started going WAY WAY up. It was used originally because it worked and was better than SharePoint (obviously) but a bit awkward to do stuff. The new versions are so much cleaner, easier to create meaningful content on, and more pleasant. This caused people to start to go beyond what they "had to do" to making it the repository of choice for basically everything. Attachments went WAY down as it was easier and faster to make nice looking content in the wiki than it was in Word (where before it wasn't easy and some stuff just couldn't be done). This all came down to the features. I actually, on the dashboard, have a "where to start" block with links to:

* Atlassian high level page of all the Confluence features
* Atlassian user documentation
* Links to the keyboard shortcuts (once people get used to this they become rabid converts to creating EVERYthing in Confluence)
* Descriptions of all the additional macros I've added and documentation for them.

I also started a "What's new on the wiki" space and update it regularly and have another set of pages where any time someone does something neat/cool/solves a problem, they can drop in a "how to". I basically got the users involved in the whole roll-out and expansion and the growth and training became organically self-sustaining

Good luck

Mike