Blog

Recently, a number of Confluence sites were accidentally upgraded to the new editing experience. As a result, all new pages and any existing pages that were edited made use of the new experience - without any advance notice.



How to undo the changes

We have since rolled this back, so any new pages you create now should use the old editing experience.

Existing pages

Any existing pages that you had opened during this time will have gotten converted to the new experience. To undo this:

  1. Publish the page

  2. Go to the page history and revert back to a previous version from before it was converted (this will not cause the current version to be deleted)

  3. Revert again to the latest version.

This should result in your latest changes showing up using the old editing experience.

New pages

If you published a page for the first time during the time that this was turned on, it cannot be converted to the old editing experience. However, you can copy and paste your content onto a new page, and the new page should use the old experience.

Drafts

Any drafts (pages that have never been published) that you worked on during this window will open in the new editing experience. In order to use the old experience, copy and paste your work onto a new page.




Why did this happen?

This occurred as a result of some performance optimizations which treated certain sites as ‘new' and thus upgraded them to all the latest features. We’re deeply sorry for this. We know that sudden unannounced changes, particularly on this scale, can be hugely disruptive and jarring. This is not how we release new features.


When the new editing experience does get turned on for all pages on your site, you can expect:

  • Ample advanced notice, with both in-app and external communications

  • A trial period in which you can use the new experience at your own leisure before it replaces the old one.

  • Temporary access to the old experience, even after the new experience is fully rolled out.


If you have any further questions about this, or need anything else, please let us know on Community and we will help you out. 

Sometimes, in the history of Confluence, we've added an easier way to do something, without remembering to take away the difficult way of doing that thing. There was a time when you had to open the macro browser and find the strikethrough macro just to add a line through your text. We later added a strikethrough button to the toolbar (which is much faster!) but still kept that strikethrough macro around.

But we've been hearing from customers that these outdated macros add unnecessary clutter and make it difficult to discover the more powerful macros like the roadmap planner or the table of contents. So, in our latest round of improvements, we've decided to clean up the macro browser.

Below you'll find a list of the macros that are being removed, and the alternative methods you can use to get the same results.


Obsolete macros 

MacroAlternative method
Align

Align your content by using the align options in your toolbar

Background colorUse a panel
Center

Use the center align feature in the toolbar

CheeseType "I like cheese!" (smile)
Confluence news gadgetLink to https://confluence.atlassian.com/cloud/blog
Content by user

Create a normal link to a search for the author using the following link structure:

https://SITE.atlassian.net/wiki/dosearchsite.action?cql=creator+%3D+%22USERNAME%22

For example, if I wanted to search for everything created by Desiree Conceicao on connie.atlassian.net, the link would be

https://connie.atlassian.net/wiki/dosearchsite.action?cql=creator+%3D+%22dconceicao%22
Copyright

Use native ©:

On Windows, press the Alt key and hold it down while typing 0169 on the keypad.

On Mac, press the Option key and hold it down while typing g on the keyboard.

Create space button

Create a link to the following URL, substituting your own site name:

https://SITE.atlassian.net/wiki/spaces/createspace-start.action

For example, on connie.atlassian.net, the link would be

https://connie.atlassian.net/wiki/spaces/createspace-start.action
Fancy bullets

If you want to use images or symbols as your bullets, you can still achieve a similar effect by adding them in manually, and indenting your list (although your bullets won't be outside of the indent). 

Alternatively, f you're planning on printing a page with bullets, you can export that page to PDF, and use Confluence's PDF stylesheet function to style your bullets however you'd like. 

Favorite Pages

Create a link to the following URL, substituting your own site name:

https://SITE.atlassian.net/wiki/my/saved-for-later

For example, on connie.atlassian.net, the link would be

https://connie.atlassian.net/wiki/my/saved-for-later
GalleryInsert images directly
Global reportsYou can already get all this information through space tools
HighlightUse a panel
HTML comment

If you want to leave a comment on a page that isn't visible to your readers, you can do this by making the text white. Alternatively, add a change comment when you publish your page.

IM presenceIf you need to know whether someone's online, it's probably easier to check that messaging service than to create a page with this macro on it. 
LoremipsumUse one of the many online tools for generating placeholder text like https://www.lipsum.com/
MultimediaDrag and drop media directly onto the page
Navigation mapUse the children display macro
No formatUse the code block macro
Privacy markInsert a link to your privacy policy
Recently used labels

Use the more functional Related labels or Content by label macro.

Registered Trademark

Use native ®:

On Windows, press the Alt key and hold it down while typing 0174 on the keypad.

On Mac, press the Option key and hold it down while typing r on the keyboard.

Search resultsCreate a normal link to search results page directly for your keyword(s)
Service MarkUse superscript and type SM
Space attachmentsAdd a label to all the pages with attachments, then use a content by label macro
Space detailsCopy/paste your space details from space tools
Strikethrough

Add strikethroughs to your text by using the strikethrough option in your toolbar.

Trademark

Use native ™:

On Windows, press the Alt key and hold it down while typing 0153 on the keypad.

On Mac, press the Option key and hold it down while typing 2 on the keypad.


Other macros being deprecated

The JUnit Report Macro doesn't get used in Confluence Cloud, so we're removing it.

The other macros listed here do get used, but their main use case is to make content look better and more readable - which is something we're now building into the editing experience as a default. As we're moving closer towards a WYSIWYG (what you see is what you get) editor, we also want to remove macros like this as they have the potential to break pages.


  • Rollover
  • Div
  • Span
  • Style
  • JUnit Report
Changes to setting a site home

We're rolling out consolidated sidebar navigation as part of the new Confluence experience, which we believe will provide a more consistent experience for all users. So that everyone gets the benefit of the new navigation, we're making a slight change to what you can set as a custom site home.

If you're a Confluence admin, you're able to set a space as the default site home for your users. Whenever a user goes to your Confluence site address (https://yoursitename.atlassian.net/wiki) or clicks the site logo at the top left, they land on the overview (previously called the space homepage) of the space you chose. This won't change—users will still land on the space overview—but now the Confluence sidebar will be visible instead of the space sidebar, and the name of the space overview you've chosen added to the Confluence sidebar. This means you can still customize the content your users will see on the Confluence site home, but the sidebar will be consistent for everyone.

 

 

If you change the Confluence site home, make sure everyone who uses your Confluence site (including users who aren't logged in, if your site's public) has permission to view the space you choose, and that there are no view restrictions on the space's overview page. Otherwise, anyone who can't see the space overview you choose will see the default site home instead.

Setting a personal homepage

We've also taken a good look at the option, currently available to each user, to choose a personal homepage. As you can bookmark any page you visit regularly in your browser, and to keep things consistent, we're removing this option in the new Confluence experience.

 

You may have heard we're rolling out a shiny new version of Confluence, and there are some big visual changes. As part of the process, we've been looking hard at how and why you customize individual space colors (if that's something you do) and whether that customization works with the new Confluence experience.

We've switched to using a layered navigation so you can easily get to the things you need most. Key actions, like search and create, are in the global sidebar (blue by default), and space-related things are in the space sidebar (which is gray). These two always need to be distinguishable from one another so you know where you're working and which options should be available. Allowing different color schemes for each space means there's a reasonable chance some users will be confused when they encounter different sidebar colors in certain spaces.

We also want to provide a consistent experience, where the colors of text, links, headings, and navigation items don't negatively affect readability or accessibility.

Because of these reasons, we've removed the ability to set a color scheme for each space. You can still, of course, have an avatar for each space, and, Confluence admins, you can still brand your instances by adding a logo and title, and choosing a color for the global sidebar. To provide an easy transition, and the best possible Confluence experience, we'll automatically migrate existing logos and header colors over to your new sidebar for you.

Add-ons and space colors

Although we've decided changing the global sidebar color for specific spaces isn't a core part of Confluence, the good news for fans of space customization is we are allowing add-on vendors to add this functionality. If you'd like to change the color of the sidebar for particular spaces, and customize Confluence in other ways, check out the theming add-ons on the Atlassian Marketplace.


We've been working on the new Confluence experience a while now—continually refining it based on feedback, while slowly releasing it to more Confluence users. We're pleased to announce that in the next couple of weeks we'll be turning the new experience on for everyone. A big thanks to everyone who took the time to send us feedback—it really helps us build the best Confluence.

If you haven't yet seen the new Confluence experience, or previously opted out, and would like to know what's in store, check out our info page. The FAQ section covers some common tasks, and how to complete them in the new design. Once everyone is using the new Confluence experience, we'll also update our documentation to help you out if and when you need it.

We're not done yet, though! We'll never stop refining Confluence, and your feedback plays a vital role in shaping the Confluence user experience. Hit Give feedback in the sidebar if you have anything to share with us.

We hope you like the new Confluence experience, and, most importantly, it helps you get more done and makes team collaboration even easier.


Confluence already lets you store a wide range of files to share and discuss with your team. We're making updating and managing those files even more convenient with the launch of our new "Edit with app" feature. It lets you open files stored in Confluence with your desktop apps and edit them, then automatically re-uploads the updated version to Confluence. Now you can get feedback on that preso, edit it in Powerpoint, and have it back on Confluence in no time.

Edit with app replaces the old "Edit in Office" feature, which came with some pretty gnarly prerequisites meaning it was restricted to a few of you with the right operating system and browser combo.

To edit a file:

  1. Click on the file to open the file preview
  2. Click Edit with at the top right of the preview window and click the default app listed
    The first time you click Edit with we'll prompt you to download the Atlassian Companion desktop app, which'll enable the download and re-upload of your files.
  3. Edit the file in the relevant desktop app and save it
  4. Head back to Confluence and hit Update to confirm you want to store the updated file as a new version

 

.

 

.

Some apps will try to change the file format when saving—from .docx to .odt for example. If the app doesn't use the same format by default and tries to change it, it'll confuse the Atlassian Companion app and the file won't automatically re-upload. Edit with app works when you save the file in the same format as was stored in Confluence.

 

.

Looking for similar functionality for Confluence Server? Check out KontextWork's awesome GoEdit add-on on the Atlassian Marketplace.

Due to changes to our Atlassian Cloud infrastructure, we'll soon remove the ability to browse and manage Confluence Cloud pages and files using a WebDAV client. Our documentation has reflected this for quite a while, so this post is just to let you know we're in the final stages of preparation for this change.

There's no action required on your part, but your WebDAV client won't be able to browse pages and attachments once we complete this change.

In the past WebDAV was also necessary to import spaces with large attachments. We're not constrained by the size of attachments any more, so you won't need WebDAV for space import.

In the new Confluence, we're making spaces more consistent in both their look and navigation options to ensure a consistent experience for all Confluence users. As part of this, we're removing the ability to add custom content to the sidebar using wiki markup. To make sure you can link to other important content, you can still add shortcuts to the space sidebar.

This change will take effect when your Confluence site moves over to the new-look Confluence, which we've just started gradually rolling out. If you have custom content in space sidebars that you'd like to keep, we suggest copying it to somewhere that's easily accessible, like the space homepage.

We believe having consistent space sidebars is the best way to help you get the important stuff done. If you think there are things we should add to the space sidebar, head over to your profile pic (at the bottom left in the new Confluence) and send us some feedback. We love getting your feedback on these updates—it really helps us build the best Confluence experience.

A while back we announced that the Office Excel, Office Powerpoint, Office Word, and PDF macros were going away. Well, the great news for fans of those macros is we've changed course and have released a new file viewer for them.

A note on the Excel macro

We've received feedback that the Excel macro doesn't meet expectations in some cases. There are some known issues with it right now, which are detailed below. So why are we proceeding with the rollout? We're making infrastructure changes for the overall benefit of Confluence users, but they mean that we can't keep the old Office and PDF macros working much longer. We need to proceed with the rollout so we can move forward with the infrastructure changes that have a much wider impact than this macro.

In saying that, we, of course, genuinely care about every user's experience with Confluence, and always want it to be the best. If you're having real trouble with the new file viewer in the Excel macro, comment on this issue and let us know. There unfortunately isn't a short-term fix, as we do need to move off the old Excel macro, but we'll keep working on a better solution for the Excel macro.

 

You don't need to do anything different—just attach the file to the page then add it using the relevant Office or PDF macro as you did before. Content you add with these macros will look slightly different in the new file viewer—multi-page documents scroll rather than display all at once down the page—but we believe it's an improvement on the previous experience. Importantly, your documents display at their full width rather than as a thumbnail.

Here's an example of a Word doc using the new file view:

 

 

We're still working on the whole experience of working with Office files in Confluence, and we hope to bring you more updates very soon. Watch this blog for updates on the Edit in Office feature.

Current limitations of the new file view:

  • Some landscape Excel spreadsheets don't display as expected
  • You can't select the specific sheet to display from an Excel spreadsheet (there was an existing bug with the old version, which meant that property didn't work anyway)

If you have feedback or any problems, please comment on this issue. We'll keep working on this feature and release improvements as soon as they're ready.

We hope you like the new file viewer for the Office and PDF macros.

 

We've been very excited recently about the rollout of collaborative editing in Confluence, and the changes it's made to the way we work. Instead of having to take turns making changes to a page in a meeting and worrying about merge conflicts, you can now edit a page simultaneously with your colleagues.

So, if you're working on a project document with someone else, it's far easier to maintain consistency and ensure you're not doubling up. It doesn't matter if in you're in the same room or oceans away, you can see what your teammate is typing as they type it. Way easier than sending emails back and forth.

The arrival of collaborative editing has, however, meant changes to Confluence's editing and publishing flow.

Why? In a collaborative editing world, you might write something, someone else might go and change half of those words, and then a third person could jump in and add something more to the middle of that. Attribution becomes much more complicated.

As a result, if someone jumps into the editor, makes some changes, and then decides the page was better off without them and hits discard.... it doesn't just discard what they've done. It discards what everyone's done. 

Yup, that's right. You might be working away happily on a page and someone else can jump in, think 'oh this wasn't where I wanted to be' and unwittingly hit discard. All of a sudden, your changes are all gone. 

As we've been gradually rolling out collaborative editing, this has been a problem that's come up for a lot of youAfter a bunch of user testing and numerous discussions with stakeholders, we've made the decision to remove the discard button.  

Removing the discard button means two things for you: 

  1. You no longer have to worry about getting rid of all of your colleagues' changes by mistake. 
  2. You'll need to use undo (Ctrl+Z) to discard your personal changes.

Confluence does save each separate version of a published document, so if you've been hitting the update button and publishing your changes as you go, you can simply revert back to a previous version. 

If you don't want to publish something until it's ready, you can also copy the page or draft elsewhere. Make the copy private, publish it after each edit so that Confluence saves each of those as separate versions, then when you're happy with it, copy that content back into the original. 



Improvements to your editing and publishing flow

We've been working on some other changes to make it easier for you to keep track of drafts and unpublished changes. 

Find your drafts with the rest of your work: Your drafts will now appear in Recently Worked On, so they're easier to get back to. They'll also have a Draft lozenge next to their names so you'll always be able to differentiate them from a published page.

Keep track of changed pages: Any published pages that you've edited but not yet updated will show an Unpublished changes lozenge. Only people who've made unpublished edits will see this, so your viewers will have no idea that the page is any different under the hood.

Save and close with less anxiety: We know the Close button caused some confusion, so we've replaced it with Save and close. This will save your draft and close the editor. If, on the other hand, you want your page to go live, hit Publish on a draft, or Update on an already published page.

Know more before you publish: We know that when numerous people are editing a page together, it can be stressful deciding when to publish. So we've added some more information, including who the current editors are, and when each of them made their last edits. This way, you can make a more informed decision about whether to go ahead and hit that Publish button or to hold off for a little longer.

Thanks

Thank you so much for your patience and involvement. We want you to know that we do read every single piece of feedback, even though we can't reply to all of them - and that we really do care. 

We are still working on improving the editing and publishing flow, so please continue sharing your thoughts and experiences with us. Hearing about how you use Confluence helps us to make it better. 

You can leave feedback here or sign up for user testing here

Removing the trackback feature

We're always working to make Confluence as simple to use as possible, so people and teams that've never used it can start working and collaborating as quickly as possible. At times this means making the decision to remove features we've added, but which haven't had the use or added the value we originally thought they would.

We've taken the decision to remove the trackback feature from Confluence Cloud, as, although it may be useful to a small number of you, the vast majority of Confluence users don't use it. We'll remove it in the next few weeks, and there shouldn't be any other effects resulting from its removal. 

If you've never heard of trackback, or just don't use it, feel free to ignore this post! If you do use it, though, and have concerns about its removal, let us know with a comment on this issue. We're always keen to hear your feedback, as it really helps make Confluence better.

Keep on collaborating,

The Confluence team

We're upgrading our Atlassian Cloud infrastructure, and, as a result, some Confluence Cloud sites may temporarily lose access to the Import from Microsoft Word feature. The Edit in Office feature may also be limited to those of you using Internet Explorer 11.

Why do we say you "may" temporarily lose access? We're rolling out our infrastructure changes very slowly, so there's only a very small chance you'll be affected by this limitation. We're doing it this way to try to minimize any disruption. If you have any concerns, contact our support team and they'll be happy to help out.

If you're like many Atlassian Cloud admins, you're managing users and permissions across multiple apps—particularly JIRA and Confluence. It makes sense to be able to do this in one central location, rather than going to each app to make changes. 

We're now beginning the process of gradually rolling out unified permissions to Confluence. Once the change lands on your Confluence site, it means you can manage access to Confluence and the Confluence admin permission via System administration, regardless of the app you're in. You'll know the change has hit your site when those permissions are greyed out in their current location,  > General configuration > Global Permissions.

To manage these permissions once the change has taken place, head to  > User management > Application access and hit View configuration

About this article
By Desiree Conceicao, published July 13th, 2016

Save time and avoid duplication

The most efficient way to help someone is to help them help themselves – and a good troubleshooting article does just that. Troubleshooting articles are a great way to document issues and provide immediate help to common or easily solved problems, letting you save your time and effort for more important endeavours.

When you first create a troubleshooting article, Confluence automatically creates an index page in your space sidebar so you can find all the troubleshooting articles within a space in one place - where they can be ordered by title, creator, or date modified.
 

To use the troubleshooting article template, choose the Create button from the sidebar, then select Troubleshooting article.

1. Choose a title and label

Most users will find your troubleshooting article by searching for it, so the best way to make your article easy to find for the relevant audience is to name it after the problem you're trying to solve, using the terms your users are likely to type into the search. 

If, for example, the problem you're troubleshooting is that you can't change the permissions for a page, you might call your article Unable to change Confluence page permissions/restrictions.

Add labels to your articles to make them easier to find and organize. Users can search by label, or use a Content by Label macro to generate a list of all the content tagged with a certain label. 

The troubleshooting template automatically adds a 'kb-troubleshooting-article' label to your document, but you can also label your article with the topics it covers or with any other categories that it falls into. There is no limit to the number of labels you can add, or to the label combinations you can search for.



2. Describe the problem and symptoms

Describe the problem as the user would experience it, and be as clear and unambiguous as possible. Even if you think your title is self-explanatory, your readers might not be certain that it's the same problem they're experiencing unless you give them more details.

For the above example, you could say: "When I'm on a Confluence page and click the Restrictions padlock icon, the names in the dialog box are greyed-out and it won't let me add or change any of the permissions."

3. Possible causes and solutions

If, as in the example above, there's only cause – that is, the user doesn't have permission to change anyone else's permissions – you can jump straight into the cause and possible solutions.

For more complex problems that have multiple causes, each with their own possible solutions, put these in a table or have separate sections for each. In this case, use a Table of Contents macro to make it easier for your readers to navigate through the information.

  • When you're writing this section, ensure you keep it simple. Use subheadings and bullet points where possible, so it's easy to follow along.
  • Break every step down into its components. Instead of saying, for example, "Check who the space admin is", say "Choose Spaces > Space directory in the Confluence header, then choose the Space Details icon beside a space. The space admin will be listed there."
  • Try to avoid using jargon. If you can't avoid it, try either defining it in a Panel macro or Info macro, or hyperlinking those terms to another page with more information about them.
  • Use screenshots, diagrams, and visuals – it makes your article easier to read, and can be used to make some of your steps clearer.

4. Related content 

Make your article even more useful by adding some related content at the end.

  • Similar or related issues – Help your users find similar or related issues by clicking on the Content by Label macro at the bottom of your page and editing it to choose the appropriate topic labels.
  • Tips and tricks – Got any ideas to help prevent the problem you tackled from happening again? Share some tips and tricks with your user with a Tip macro.
  • If you use any JIRA application – Add a JIRA Issues macro to your troubleshooting article to provide quick access to known issues. This has the added advantage of automatically updating when an issue is resolved or its status changes. 

  • If you use Questions for Confluence – add a Questions list macro to troubleshooting articles, to highlight the top questions with the same topic as the article, and an Ask a Question button to the knowledge base homepage. 



Pro tip

When you create your first troubleshooting article in Confluence you'll a page properties panel at the bottom of the page. The Page Properties macro works in conjunction with the Page Properties Report macro to let you create a summary page that pulls in information from multiple pages.

You can choose what information this captures, and can put any fields into this macro. This is especially useful if, for example, you want to create one page for all the troubleshooting articles across your organization.

5. After publishing

Once you've published your article and shared with the rest of your team, users can use inline comments if they need further clarification or help with any of the information you've shared.

When you've dealt with an inline comment, click Resolve and it'll disappear from the page.

You can always find resolved comments again under the more actions menu  to help you track what your readers need additional help with.


Bonus: Customize the troubleshooting template to fit your team's workflow

You can edit the troubleshooting template at any time and tailor it to fit your team's specific needs. If you want to edit the template for your specific team or project, go to the Space Tools menu and select Content ToolsUnder the Templates option you can view and edit any of the templates included. If you're a site admin you can also edit the global template to customize it company-wide.


At a glance: what did you just learn?

    • Troubleshooting Article template: It does most of the work for you. Follow the page outline, and fill in content that makes sense for your specific requirement.
    • Troubleshooting Article Index: Once you've created a few troubleshooting pages, you can see all the high level details at a glance on an index page that Confluence automatically creates when you use the template.
    • Page Properties macroThis macro makes it possible to create a reporting page across all your troubleshooting articles. When using the template, it will be included on your page.
    • Content by Label macro: This is used to display lists of pages, blog posts, or attachments that have particular labels.  
    • Table of contents macro: Creates a table of contents based on the page headings.
    • Info, Tip, Note and Warning macros: Allows you to highlight important information.
    • JIRA Issues macro: Create and display dynamically updating JIRA issues on your Confluence page.
    • Customizing templatesYou can edit any of the templates that come included in Confluence to fit your specific workflow.


 

Hungry for more?

Watch the blogs in this space to get notified when new tips articles like this are posted.

 Find this page helpful? Share the love on Twitter or LinkedIn

About this article
By Desiree Conceicao, published July 13th, 2016

Harness your organization's collective knowledge

How-to articles let you share valuable knowledge across your organization in a way that requires little time or effort. They're useful for creating consistency, formalizing processes that people might be unsure of, and helping new team members be more productive right off the bat.

Confluence comes with a default how-to article template, which you can customize for each space to make writing your how-tos as quick and easy as possible. And, when you first create a how-to article, Confluence automatically creates an index page in your space sidebar so you can find all the how-to articles within a space in one place - where they can be ordered by title, creator, or date modified.
 

To use the how-to article template, choose the Create button from the sidebar, then select How-to article.

1. Choose a specific title

What are you teaching people to do? Choose a descriptive title that matches up with what your users are likely to search for when they want to solve that problem. If you've got a long list of how-to articles, naming them all "How-to do whatever" can make your list hard to scan. Instead, you can also make use of variations on this, like "How do I get more statistics from Confluence?" or "Capturing HTTP traffic using Wireshark or Fiddler".
 

2. Add some labels

Adding labels to your articles makes them easier to find and organize. Users can search by label, or use a Content by Label macro to generate a list of all the content tagged with a certain label. The how-to article template automatically adds a 'kb-how-to-article' label to your document, but you can also label your article with the topics it covers or with any other categories that it falls into. There is no limit to the number of labels you can add, or to the label combinations you can search for.

3. Write an introductory overview

Why do people want to do whatever you're teaching them, and in what situations? For example, if you were writing a How to clean the office dishwasher article you could explain that this needs to be done every few weeks to prevent the clean dishes from starting to smell like sewage water. This helps explain the value of whatever you're teaching and lets your users know when it is or isn't appropriate to do it.

4. List anything they might need or should watch out for

Does your user need to have a specific piece of software installed? Do they need any special permissions? Will they require a wrench to do this job? You can use a Tip or Info macro to highlight this information. 

If this how-to is conditional, or if there's anything that might prevent them from being able to use it, let them know with a Warning macro. This could be, for example, letting your audience know that a piece of software you're providing installation instructions for is not supported on very old versions of Windows.

5. List the steps

Go through each step using clear, simple language.

  • If there are a lot of steps, add a Table of Contents macro to your page, so it's easier to navigate.
  • Format your page so that it's easy to read. If each step is quite long, choose a brief heading for each step, then put the rest of the information in a paragraph underneath it. Where applicable, use bullet points instead of dense paragraphs.
  • Break each step into its components. Your users might not find everything as obvious as you do, and it helps prevent ambiguity and mistakes. Instead of saying "Check who the space admin is", say "Choose Spaces > Space directory in the Confluence header, then choose the Space Details icon beside a space. The space admin will be listed there."
  • Avoid jargon if possible, but if you must use it, try either defining it in a Panel macro or Info macro, or hyperlinking those terms to another page with more information about them.
  • Use screenshots, diagrams and visuals – it makes your article easier to read and can be used to make some of your steps clearer.


6. Related information or tips

Use the Panel macro at the bottom of the page to share any additional information your user might find useful. For example, on a page about how to set up your printer, you might want to tell them how often they should refill the paper tray, or let them know that they can print double sided to reduce paper waste.

7. Link to related content

  • The Content by Label macro at the bottom of the template automatically pulls a list of articles by label. Click edit on the macro to choose what labels it uses and it'll automatically update the list for you every time you add that label to a piece of content. This means that if you're writing an article about how to set up your printer, for example, you can also have links on your page to "How to change the printer's ink cartridges" or "How to fix a paper jam".

  • If you use any JIRA application – Add a JIRA Issues macro to your troubleshooting article to provide quick access to known issues. This has the added advantage of automatically updating when an issue is resolved or its status changes. 
  • If you use Questions for Confluence  – add a Questions List macro to troubleshooting articles, to highlight the top questions with the same topic as the article, and an Ask a Question button to the knowledge base homepage. 



Pro tip

When you create your first how-to article in Confluence you'll notice a page properties panel at the bottom of the page. The Page Properties macro works in conjunction with the Page Properties Report macro to let you create a summary page that pulls in information from multiple pages. In this case you could use the Page Properties Report macro to create one page for all the how-to articles across your organization.


8. User test

Check that your how-to article is clear enough by user testing it on someone outside your department. If they get confused or find it difficult to do whatever you're teaching them, you may need to simplify some of your steps further or provide additional information.

9. Follow-up after publishing

Once you've published your article and shared it with the rest of your team, users can use inline comments if they need further clarification or assistance with any of the information you've shared. When you've dealt with the inline comment, click Resolve and it'll disappear from the page. You can always find resolved comments again in the more actions menu  to help you track what your readers need more help with.



At a glance: what did you just learn?

 
    • How-to Article template: It does most of the work for you. Follow the page outline, and fill in content that makes sense for your specific requirement.
    • How-to Article Index: Once you've created a few requirements pages, you can see all the high level details at a glance on an index page that Confluence automatically creates when you use the template.
    • Page Properties macroThis macro makes it possible to create a reporting page across all your how-to articles. When using the template it will be included on your page.
    • Content by Label macro : This is used to display lists of pages, blog posts or attachments that have particular labels.  
    • Table of contents macro : Creates a table of contents based on the page headings.
    • Info, Tip, Note and Warning macros : Allows you to highlight important information.
    • JIRA Issues macro : Create and display dynamically updating JIRA issues on your Confluence page.
    • Customizing templatesYou can edit any of the templates that come included in Confluence to fit your specific workflow.
  
 

Hungry for more?

Watch the blogs in this space to get notified when new tips articles like this are posted.

 

 Find this page helpful? Share the love on Twitter or LinkedIn