JIRA and Confluence Upgrade Highlights

[Neil Taylor]

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!

[Teresa Hollidge]

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. 

[Mike Rathwell]

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

[Stephen Gurnick]

The jump you are making on the Confluence side is quite larger. We did a similar big jump upgrade as well not too long ago.

The most important items to review with end-users are:

1. the new locations of buttons, features, etc. As I'm sure you can tell, a lot has changed in this regard. For example the Add new page button has moved to the top and is now called Create. For something as simple as this, I got a lot of questions.
2. explain how the new side bar works - what is it for, what does it contain, how can it be modified, how do you make it go away.
3. if you have different space admins managing your spaces, now would be a good time to review overall permissions and setting restrictions.

[Daniel Wester]

For confluence - be prepared for feedback about the loss of wiki markup (people were very possessive of the markup).

[Mike Rathwell]

When I went from 3.5 to 5.(something; can't remember now) this was a big deal for some and I had many bitter complaints. Some people really loved editing directly in wiki markup. That said, it's not TOTALLY gone; you can still start typing wiki markup but it automagically now turns into the macro/value you typed as wiki markup. This has proven to be just fine for all but the total diehards. I liked wiki markup as well but I've grown to like this even better; I can type the wiki markup to place it but then it tosses me directly to the happy friendly GUI element of the macro in question. With that and the other keyboard shortcuts I can create content faster and easier than I ever could. If you get said complaints spend some time on that.

[Neil Taylor]

Thank you everyone for all of the great advice!!