Best Practices for Сreating External Documentation Site in Confluence

February 24, 2022
#How To#Confluence Tutorial#Confluence
22 min

We all love Confluence so much for the ability to have the information at hand, open and well-organized. It makes cooperation easy as a pie and saves us a lot of time. But when it comes to creating external documentation in Confluence for our products, we can get stuck.

The good news is that all we need is already in Confluence, and documentation for our products can be ready in a few hours.  However, it can be challenging to quickly find the required information since it can be scattered across multiple Confluence pages and spaces. External users need to have limited access to all these pages and see only the relevant information. Moreover, an inexperienced user can easily be lost in Confluence. The interface we all love and find so convenient can appear not so intuitive for those who see a Confluence page for the first time.

You can be a little bit overwhelmed with all that given, however, the solution is simple yet powerful. Keep reading for the best practices for creating an external documentation site in Confluence Cloud.

Create a separate space for your documentation

For security and common sense reasons, we can’t let external users browse our whole Confluence instance. So let’s create a separate space for our product documentation and collect the information for our users there.

Confluence allows flexibility in access restrictions for separate spaces. You easily define what particular users or user groups can do across Confluence pages within a space.

As we create product documentation, we need all users worldwide to access it. Anonymous access works great for that. Navigate to the Confluence sidebar, locate Space settings > Space permissions, and click General.

space access restrictions in Confluence

Scroll down to Anonymous Access. Here you can choose the permissions for all external users of your Confluence Cloud documentation site. Be mindful that you can grant broad permissions to anyone outside your organization. Limiting anonymous access to viewing and commenting is reasonable to ensure information consistency and quality. You can read more about space permissions in the Atlassian Support documentation. We suggest enabling only viewing permission for a documentation site.

space permissions in Confluence Cloud

In this case, you can be sure that your product documentation pages remain clean and concise. Commenting is a great thing, but it can be distracting on informational pages. There are other better ways to communicate with your users, and we’ll cover them later in this article.

Organize the information in your Confluence documentation space

Once you’ve created a separate space for your documentation site in Confluence and given access to anonymous users to it, you need to think about the page structure. Even the most valuable information can become useless when readers can’t reach it effortlessly.

It’s a good idea to start your documentation site with the page tree in mind. Spend some time thinking about the logical structure of your space. You can go even further and create a quick draft on a sheet of paper to consult it while creating Confluence pages.

An apparent solution here is to create a home page with general information, parent pages for the main features of your product, and child pages for minor functions or details. You may also want to create separate sections for FAQs, releases, and other technical information. As a result, you’ll get a well-organized documentation site in Confluence that is easy to browse even for inexperienced users.

page tree in a Confluence Cloud

Other things to keep in mind

The devil is in the detail. All product owners know it for sure. When it comes to your product, you need to always be on top of things. Many great products remained unnoticed because of nuances like an irrelevant logo, title, or bad documentation.

Have you already created a product documentation space in Confluence? Presumably, you were even accurate enough in a space structure. It’s time to leverage your product documentation site with our tips.

Keep your page tree neat and skimmable

Create Confluence pages according to the chosen structure. Don’t make a complex structure where users can get lost. Believe it or not, 2-3 levels of child pages can be complicated enough for your readers. Don’t go overboard.

Keep page names simple

Don’t give readers a reason to quit. Create Confluence pages with short names. The ugly truth is that people are lazy by nature. Who would love to open the page with an academic name like “A technical documentation covering the engineering implementation, functionality, and out of scope issues of a Confluence inline macro for status tracking”? And what if you place the same information under the “Handy Status” title? It looks like this option has a much higher chance of getting read.

Be consistent

Choose the principle of page naming and follow it throughout your documentation. We love to see something known and traditional. No need to vary your page names from section to section. For example, you have a page “How to use Handy Status.” Once you create another one about Handy Date, you may write “Using Handy Date.” The idea is the same, but this inconsistency would distract readers. Stick to one model throughout your Confluence space.

Create a beautiful Confluence page for your documentation overview

Documentation sites in Confluence are easy to set up, but they can be plain and look boring for external users. A landing page with the Children display macro for navigation seems intuitive for you, but it can turn out to be unattractive in your readers’ eyes. In the end, the primary purpose of our documentation site is the satisfaction of our end user. They refer to our documentation expecting to get quick answers to their questions. Their customer journey on our public Confluence site depends on us so let’s make it a smooth adventure.

Highlight the key features of your product

You’ll be surprised, but the visitor of your documentation can know little about your fantastic product. Many users start the evaluation of the product with its documentation. They will walk through the functionality you describe deciding whether your product is worth a trial period. Use this insight to your advantage – create a top-notch documentation site demonstrating the best of your product.

The main page should be concise but informative. Create an attractive page with a brief product description, point out the key features with the bullet list, and add links to the detailed technical description.

Embed video in Confluence

We’re pressed with time and want to proceed with daily tasks as quickly as possible. Add a short demo video to help users learn more about your product. 

In Confluence, you can insert links to your Youtube videos in several ways.

First, you can insert the link to your video directly into the Confluence page. Choose the way the link is shown on a page. For better visibility, we advise the Display embed option.

Choose the way links look on a Confluence page

If public links are disabled for your Confluence instance and you want anonymous users to see them, use the Widget Connector macro. It allows you to embed Youtube videos, Flickr slideshows, Twitter streams, Google Docs, and other content from the web into Confluence pages in a few clicks. You can choose the source address and the preferrable size of your media. With this method, you can be sure that even anonymous users will reach the content on your page once you allow the public access to it.

Widget Connector macro to embed multimedia in Confluence Cloud

Add a call to action to your Confluence page

Our documentation is another touchpoint with our users. Let’s benefit from it. Add an effective call to action to your main page to trigger additional contacts between you and your site visitors. This could result in long-term relationships in the future. The only thing here is that your call to action needs to be appealing and easy to locate on Confluence pages.

At Stiltsoft, we use the Handy Button macro for that. It’s a part of the Handy Macros for Confluence app. It allows you to create Confluence-like buttons and customize their color and size. Another great thing is that you can easily reuse your Confluence content as Handy Button can lead to an external address or an internal Confluence page.

Handy Button to create clickable links in Confluence

We suggest creating noticeable links somewhere on top of your documentation page so that users can see them without scrolling the page.

external documentation in Confluence

Show the product roadmap

Your customers could be interested in the information about upcoming releases. The features you are working on can become your strength when your users know about them. Don’t go deep here, a short plan overview will be enough.

You can show a table with the product development progress from your product dashboard. Here’s an example that we suggest.

Create product roadmaps in Confluence

Simple as it is, this table gives an overview of what to expect from the product in the next few months. The user sees the feature itself, its status, and progress. To ensure that the information is always up-to-date, put the content from your product space into the documentation page using a combination of the Excerpt and Excerpt Include macros. This way, you can rapidly reuse the existing table on several Confluence pages. Once the values of the original table change, reused tables will be updated automatically.

Use Excerpt Include to reuse information in Confluence

You can effortlessly create these dashboards in your space. Your team will benefit a lot from focusing on the essential things. To start with, add the Excerpt macro to your page, create the table with statuses, add sliders for progress management.

Use Excerpt to reuse the information in Confluence

You can add the native Confluence Status macro. Type /Status to add it to the page.

Add statuses in Confluence

Another solution is Handy Status, a macro allowing you to create a custom set of statuses and easily switch them in the page view mode.

Create dropdowns in Confluence with Handy Status

Handy Slider is another macro from the Handy Macros for Confluence app. It can transform your table into an interactive infographic in a second. Just type /Handy Slider, insert it to the page, and set the value. The macro coloring changes based on its value, making progress tracking even more accessible.

Add interactive sloders to track and visualize changes in Confluence

You can change Handy Slider in the page view mode. But no worries here. Anonymous users won’t affect your data as they can’t change the Handy Slider value on a page.

Highlight the relevant content

Even though you have created an excellent documentation structure, it’s reasonable to put links to the pages frequently read by your users on the main page.

Use button lists to highlight information in Confluence

Keep these bullet lists short. Too many highlights can affect your readers in an opposite way leading to distraction from the key points.

Provide additional navigation

Your readers are newbies to your Confluence site. It’s your role to help them look around. Why not add some more navigational tools? Add the Labels list macro to create a list of labels used in your Confluence documentation space. If you’re accurate enough to update labels for your pages, you’ll get quick navigation by topic, like this one:

Users can browse Confluence content by topic with the Label list macro

A search bar is a must-have for an external Confluence site. It’s probably the best way to locate the necessary information in a few seconds. Use the Livesearch macro to embed a search box into your Confluence page to show search results as you type.

Search for information in Confluence with a search bar

You can customize its look in the settings to satisfy your needs better.

Share the event agenda

If you organize webinars, meetings, or other events related to your product and best practices, you can promote them on your Confluence documentation site. The audience coming to read about your product is presumably interested in your educational content.

You can put an announcement of upcoming events in a table generated with the help of another Confluence native macro, Page Properties Report. When combined with Page Properties, it collects the tabular data across multiple Confluence pages based on the selected criteria.

Page Properties Report in Confluence

As a result, in our example, we get a brief table overview of the webinars described on three different Confluence pages.

With Handy Macros for Confluence, you can go even further and add some dynamic macros to this table.

Handy Date is a great way to highlight the dates of future events for our use case. This macro enriches your experience with date operations in Confluence. You can change the date in the page view mode and choose the date coloring.

Add Handy Buttons to create clickable buttons on your Confluence page. Once you do it and provide the links to your webinar registration or stream record, your users will be able to enroll and take part in your events right from the documentation site.

links on Confluence pages in Page Properties Report

Move on to your external documentation

Confluence empowers its users with great tools for any need or purpose. Now you see how to organize an external documentation site without any additional development or engineering skills. Just use the native Confluence macros in combination with Handy Macros for Confluence. You can try the app for free on the Atlassian Marketplace to see how you can benefit from it. If you still have questions, don’t hesitate to contact us.

3 Ways to Make Your Confluence Links Effective

January 18, 2022
#How To#Confluence Tutorial#Confluence
9 min

Confluence is a powerful collaborative tool for companies of all sizes. Bringing teams together in this new post-COVID-19 reality, Confluence makes it easy to stay tuned, share opinions, and exchange information.

Why Confluence?

When many team members still try to eliminate social contacts, organized Confluence pages become a single source of truth. What’s the key? Simplicity and speed. You can work without switching between messages in Slack or Yammer, documents in Google or Microsoft Office, and tons of emails in your inbox. The Confluence page is a great place to create, edit, and share content. What makes it even more valuable is the ability for inline discussion and collaboration. But is the situation so clear-cut? 

What can go wrong?

As with any field of our life, it all differs. Confluence pages are great; some problems can still arise. Have you ever experienced frustration looking at endless pages piled with multiple text fragments from various authors? Trying to find something usually turns to be pick-and-shovel. 

Or remember the last time you worked on some page in a space shared by the whole company. You’ve done a great job performing deep analysis, adding lots of insights, and sharing valuable links with your colleagues. You’ve even shared a Confluence page with this information to make sure it won’t stay unnoticed. What happens next? Your team just looks through your work in a minute to never get back to this page again. All your ideas remain overlooked, no links are followed, no improvements happen. Sounds not so cool, right? 

The reason is as easy as pie: we are overwhelmed with information, so it should be well-organized to get noticed. Collecting and analyzing data is not enough. Organizing information and delivering it in small chunks is key. 

How to add noticeable links to Confluence pages?

At Stiltsoft, we love to create neat Confluence pages with valuable sources for internal use. Even if initially written as a personal draft with a flow of thoughts, any new page can become a masterpiece as it progresses. So it’s our common practice to structure information on pages in an easy-to-read manner. We often use links to internal and external sources on our pages.

Check out our top three ways to organize links in Confluence. With them, you can be sure your team never misses a thing on a page or skips a vital link.

Highlight your link for better visibility

This advice sounds like a joke, but it works. Use bold type or italics, change the font size or color. It may seem like extra work, but the result makes it different. Which part of the page do you like more?

highlight link in Confluence

Just a few mouse clicks can change the way your Confluence links look across pages. Best practices can be easy but effective in creating beautiful Confluence pages.

Add link previews for higher engagement

When you need to draw attention to particular links, their content previews work excellent. At Stiltsoft, we use Handy Cards for this purpose. It’s one of many macros available in Handy Macros for Confluence. You can create clickable links to Confluence pages or any external URLs using intuitive macro settings.

Handy Cards are highly customizable and allow to add links with previews for Confluence child pages or pages by labels, choose column or size layout, sort generated cards by creation or update, and many more. The rich functionality of Handy Cards makes it possible to link any web address to them and define its preview.

You can use Handy Cards as an alternative to the native Children Display macro. It’s a quick way to get an organized overview of all pages linked to the parent page. In a few clicks, you get a structured and engaging Confluence page.

create page previews for links in Confluence

Use buttons for CTA

Once you have a link all page readers need to follow, Handy Button is a great idea. It transforms your link to a clickable Confluence button with the text you define. Handy Button is also a part of Handy Macros for Confluence (now also available in Cloud), and it works out-of-the-box. All you need to do is to choose the color and name for your URL. After that, you’ll get a Confluence style button on your page that is noticeable even while skimming the page.

insert buttons into Confluence pages

What else?

Feel free to share your best practices of working with links in Confluence. Remember, the more we improve, the more effective our processes become.

If you are interested in any other macros from Handy Macros for Confluence, contact us by clicking the button below (and yes, this is a Handy Button (smile) ).

5 Tips to Become a Gantt Chart Expert Using Atlassian Confluence

September 7, 2021
#How To#Confluence Tutorial#Confluence#Reporting
14 min

Imagine you have to visualize a long-term project the simplest way possible. What is the first solution that comes to your mind? Most project managers would say that a Gantt chart can be a real lifesaver in this situation. This powerful tool for project planning helps you display the sequence of the main project stages and tasks, as well as their duration within one chart. For this purpose, this is the most illustrative method so far.

Consider the following situation: you are in charge of a new project. Unexpectedly, the vice president of your company has requested a detailed one-page project timeline to look through as soon as possible.

Let’s look at what you have now: 

  • all deadlines written in separate sticky notes
  • the project tasks placed on several Confluence pages
  • the key events marked in the team calendar

You’ve been given an hour to bring together all this information on one Confluence page.

In this situation, Table Filter and Charts for Confluence will help you complete this challenging task. In this blog post, we will show you how the Chart from Table macro, one of the three most popular macros of this app, allows you to easily visualize your data using a Gantt chart.

Build the simplest Gantt chart in Confluence

You can create a simple Gantt chart using a three-column table with the information about tasks and start and end days. 

Add the Chart from Table macro, choose the chart type and specify the settings.

Labels Column:

  • Task Type

Values Column:

  • Start Day
  • End Day

The chart is simplistic and bright. The diagram shows you all the main stages of the project. The system counts the number of days within each stage. When you hover over the bar, you can see the duration of the selected project stage.

Add task descriptions and completion bar

The previous chart looks good, however, it can present the information even more effectively. The chart displays the required project scopes, but the time frames remain unspecified and too long.

You can break down each project stage into your current tasks to make your chart more informative. You add a task description column to the table and specify the duration of task realization.

Add the completion column to the table to show the progress bars on the chart.

Labels Column:

  • Task Type
  • Task Description

Values Column:

  • Start Day
  • End Day
  • Completion

The bars allow you to get more information about the progress of each task.

Pro tip:

Learn more about using Spreadsheets in Confluence

Outline milestones

The chart looks much better now. However, there is always space for improvement. The app also helps you add milestones to Gantt charts.

Milestones are key events of a project. The team is not able to proceed if the milestone is incomplete. To display the milestones on your chart, you can insert the additional small table into one macro body. Do this in the edit mode.

After that, choose the settings.

Labels Column:

  • Task Type
  • Task Description
  • Milestone

Values Column:

  • Start Day
  • End Day
  • Completion
  • Date

The milestones are marked with an asterisk. When you hover over the asterisks, you can see the detailed milestones’ descriptions.

Don’t forget about planned activities

You can also mark the key activities of the project on the chart to prioritize them and to collaborate more effectively.

All you need to do is insert the events table into one macro body and set additional labels and values columns in the chart settings. The app allows you to add the “today” event.

Add the correct columns into the settings.

Labels Column:

  • Task Type
  • Task Description
  • Milestone
  • Events

Values Column:

  • Start Day
  • End Day
  • Completion
  • Date

It means that when you open a page with a chart, you will see the line that shows where you are at the moment. This way, you get a bird’s-eye view of all project stages, enabling you to see the project time frame and progress.

Last but not least, you can set dependencies between tasks. This helps you understand what you need to prioritize and complete before moving on to the next stage.

If you want to focus on a more specific period without losing the rest of the data, you can zoom the Gantt chart in. Just hold down the Ctrl button and rotate the wheel on your mouse to zoom the chart in or out. After that, you can move around the chart by pressing Ctrl (for Windows) or Alt (for MacOS) and dragging the chart in the necessary direction.

Customize your chart and share the results

Now all you need to do is change the bars’ colors and set the titles to match your brand book guidelines.

You can select more appropriate colors for each type of task or each task in particular.

If standard app colors don’t match your company style or simply don’t satisfy you, specify the colors for each task in a table.

Pick colors from this list or set your HEX codes.

Now that you’re ready with all the information on the project, it’s time to present your boss with the Gantt chart you created.

Here’s how you can share your Gantt chart with your boss and your colleagues:

  • export the Gantt chart or the Confluence page to Word or PDF
  • share the link to the page

Since your boss asked you to show the project schedule in Confluence, the second option would suit you best.

Bonus tip: make your Confluence tables and graphs look more professional

We created a Gantt chart from scratch with the help of the Table Filter and Charts app, but you can do a lot more. Try this handy solution for free to discover all of its features:

You can manage your tables in Confluence on the fly using a bundle of this app’s easy-to-use and fully customizable macros. Check out how user-friendly features Table Filter and Charts are and elevate your tables in Confluence to the next level.

If you have any questions, feel free to comment on this blog post below or contact us.

Two-Minute How-To: Creating Buttons in Confluence

September 1, 2021
#How To#Confluence Tutorial#Confluence
7 min
Add more interactivity to your pages in Confluence Cloud for instant switching of statuses in the view mode with Handy Macros for Confluence

If you have read our previous how-to blog posts, you know that the ‘look and feel’ of Confluence is way more flexible than it seems to be. In this article, we’re going to explore how the Atlassian User Interface (AUI) library can help with improving Confluence usability. AUI allows you to do a lot of things, but for now, we will focus on buttons. Creating buttons in Confluence is a cool way to make links more visible on your pages. Atlassian doesn’t recommend using buttons as links, however, as we will see further, sometimes you can deviate from this rule.

Let’s see an example of how buttons can be used. On the home page of our documentation, we have several icons of our apps. We wanted to place a link that would take users to the support request form in case they don’t know how to proceed or need more information.

Since we wanted to make this link easier to find on the page, we thought it would make sense to put a button, because, first it would be easier to find the link on the page. And second, the button would be in line with the product icons.

button in confluence documentation

Creating buttons in Confluence

So how exactly can you place a button?

Open the administration panel and click the User Macros tab. Let’s create a user macro called aui-button with the following code:

## Macro title: AUI Button
## Macro has a body: N
## @param Title:title=Title|type=string|required=true
## @param URL:title=URL|type=string|required=true
<a href="$paramURL">
    <button class="aui-button aui-button-primary">
        $paramTitle
    </button>
</a>

Then save the macro and make sure it appears in the macro list.

creating buttons in Confluence

Our macro is now available in the macro browser. Click Insert More Content in the page edit mode and open the Other Macros tab. Enter the name of our custom macro and insert it to any page. All you need to do is to set its name and URL.

add button to Confluence page

You can also add a small question mark icon to the Get Help button, it’s enough to take the default code for the icon button and replace the default code with the following:


    <button class="aui-button">
        <span class="aui-icon aui-icon-small aui-iconfont-help">
            Help
        </span>
        <span>
            Icon button
        </span>
    </button>

You can immediately see the result of your experiments.

creating buttons with AUI

Making your pages engaging and interactive

You can try Handy Macros for Confluence to create buttons of different colors and make sure that the link opens in the new tab.Handy Button in Confluence

Moreover, this app provides various ways of how you can diversify your content in Confluence Data Center and Server with the help of such macros as:

  • Handy Status: create custom status sets and changes statuses on the fly in the page view mode
  • Handy Reminder: add reminders right to Confluence pages
  • Handy Carousel: organize your images and videos and create dynamic media galleries
  • Handy Heading: copy link to any page heading in one click
  • Handy Cards: preview your Confluence pages as a card grid
  • and many more macros

Add more interactivity to your pages in Confluence Cloud for instant switching of statuses in the view mode with Handy Macros for Confluence.

Two-Minute How-to: Adding Charts in Confluence Instantly

April 6, 2021
#Reporting#How To#Confluence Tutorial#Confluence
6 min

Presentation is often a vital part of working on a project. If you want to visualize data and show it to your colleagues, you’ll probably do it with charts and graphs. Such demonstration is both appealing and easy to understand.

Table Filter and Charts for Confluence allows you to produce charts quickly and efficiently. With this app, you can:

  • build charts and graphs in a few clicks
  • choose ready-made charts based on your table, or customize them yourself
  • select the most suitable chart type and convert it to 3D
  • aggregate table data before creating a chart

In this blog post, we’ll show you how to add Confluence graphs in a moment.

How to add a chart with a wizard

First, open a page with your table and hover over it. Click the  button on the right. Choose the Create a chart from data series option.

Next, you’ll see the types of charts you can add. Click on the one that appeals to you the most.

The Table Filter and Charts for Confluence app analyzes your table and suggests you various chart options. For each chart type, you’ll see a few methods of data organization. To insert a chart, choose the preferred option.

If you want a chart that differs from the app’s suggestion, you can always create a custom graph. Choose the Custom button at the end of the list, then select a chart type as well as labels and values columns.

You can adjust Confluence charts of the fly if needed. If you hover over a chart, the settings menu will appear on the right. In this menu, you can change labels and values columns, modify your chart height and width, and switch to a different chart type.

Adding a chart in Cloud

The mechanism is very similar in Cloud too. When you open a page with your table, choose the button in the top right corner.

Then select the Chart from Table macro.

All of the following steps are the same as in the Server version. Add one of the suggested charts or customize your own. Depending on your case, you can choose various settings and adjust charts in Confluence to particular needs.

Useful tips

  • Chart colors are chosen automatically, but you can always change them to suit your brand book or in case you just like a different color scheme more. Click the cogwheel icon, press the Select colors button, and pick more suitable tones.
  • If you need to hide the table your chart is based on, open the settings with the cogwheel icon and press Hide the source table.
  • If you need to use your chart outside Confluence, you can export it as an image, PDF, or Word file. Press the cogwheel icon and select the suitable option.

Now that you know how easy and quick inserting tables can be, try it out for your projects and reports. If you have any issues or questions, contact us.

Try Table Filter and Charts for Confluence Cloud for free

Related posts

Two-Minute How-To: Creating Polls in Confluence Cloud

November 17, 2020
#How To#Confluence
4 min

What is the best way to get instant feedback from your teammates or blog audience? Polls and surveys definitely do the job.

Let’s quickly recall three use cases where you can benefit most from polls and surveys.

1. Gathering votes from your teammates

With the help of polls, you can collect actual data to find the optimal solution for your task. Make sure that you hear the voices of your teammates before making a final decision in questions that require the involvement of the whole team.

2. Collecting feedback

If you’d like to get instant feedback on the results of your work, you can simply ask the audience. This information will help you improve and provide more relevant results next time.

3. Creating engaging and interactive content

While writing a blog post, surveys allow you to do your research on the go. They also can help you get to know your colleagues better. Moreover, posts become very engaging for readers when they have the opportunity to reflect on the content with the help of your questions.

How to create a poll in Confluence Cloud

The Handy Poll macro is bundled in the Handy Macros for Confluence Cloud app. The macro allows you to add a poll to a Confluence page in a few steps.

If you have any questions regarding the app’s features or would like to suggest a topic for the next Two-minute How to, feel free to contact us. Stay tuned! 🙂

Try Handy Macros for Confluence Cloud for free.