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) ).

How to Create Reports from Multiple Confluence Tables

October 1, 2020
#Reporting#How To#Confluence Tutorial#Confluence
9 min

In this blog post, we continue to describe how to enhance Confluence with the help of the Table Filter and Charts for Confluence app. Let us guide you through another widespread use case from our customers.

You’ll learn how to collect tables with multiple rows on one Confluence page, merge them, and make the final report easy-to-read.

Use case

You have a lot of similar tables with multiple rows across your corporate Confluence instance. For example, let’s assume that all the departments keep track of minor expenses in their own spaces. To find these tables easily, users set the Accounting label onto every related page.

The task is to collect information throughout the company and create an intelligible combined report on all the local expenses.

As the tables have several rows, the standard Page Properties Report macro won’t work for you. Manual copy/paste is ineffective and full of mistakes. Besides, your final table will be a large one, and you’ll need some additional tools to make the report clear.

Collect tables with multiple rows on one page

To collect several tables with multiple rows on one page automatically, use the Table Excerpt/Table Excerpt Include macros.

Wrap every source table in the Table Excerpt macro and assign it a unique name.

Then go to the required page and insert the Table Excerpt Include macro. Specify your Table Excerpt macros’ name and choose to look for them onto every page with the Accounting label.

As a result, you get all the local tables placed one after another on the same page. Note that all the changes made to the source tables are immediately reflected in the reused tables, and you don’t need to update anything manually.

If your hosting type is Cloud, the next step is to wrap your Table Excerpt Include macro in the Table Toolbox macro. The latter helps you to nest several macros required to perform additional operations with the reused tables.

For Server and Data Center instances, you drag and drop macros to place them inside each other or change their order.

Pro tip:

Learn more about using Spreadsheets in Confluence

Merge tables

To merge several tables into one big table, use the Table Transformer macro. Wrap your Table Excerpt Include macro into its body. As you have identical column names in the reused tables, choose the default automatic Merge tables preset.

Use pagination

To make your large table easy-to-read, let’s add pagination. Wrap your Table Transformer macro into the Table Filter macro and go to the Table View tab. Find the Number of rows per page field and set the required value.

Filter your combined report

To achieve more from the final report, locate the Filters tab of the Table Filter macro and choose any filters you need. For example, let’s set two dropdown filters for the Department and Accountant columns and an Icon filter for the Priority status.

Now you can save the Table Toolbox macro and enjoy the result:

  • The combined report is generated automatically, and all the changes made to the source local tables are reflected instantly.
  • The final big table looks compact and neat due to the pagination feature.
  • Different Excel-like filters allow you to find the required information without routine manual work.

Don’t forget to check our recent blog posts related to the capabilities of the Table Filter and Charts for Confluence app:

The app can also help you with many more customized use cases regarding native Confluence tables and dynamic macros, such as Page Properties Report, Jira Issues, Content Report Table, etc.

How to Manage Requirements in Confluence

September 3, 2020
#Document management#Analytics#How To#Confluence Tutorial#Confluence
8 min

More and more companies use Confluence to accumulate data, share ideas, plan projects, track meetings, assign tasks, collect feedback, etc. In this blog post, we’ll talk about one of the most common cases that Confluence allows to accomplish: you’ll learn how to manage requirements effectively.

Use case

Your company develops multiple software apps for different customers. To keep track of the specifications, you create separate Confluence pages for all the technical details. Your teammates work on their projects, updating the corresponding pages.

To organize the workflow, you ask your colleagues to leave standard comments when making changes to the requirements page.

  • Application Review stands for any updates to the functionality of the app.
  • Clearance Review goes for the changes related to the application security.
  • Office Action is left when your co-workers combine the final document and send it to the customer.

If the changes are minor and insignificant (for example, typos and missed words), there are no comments.

The task is to track how many improvements (including their type) your colleagues have made and how the workflow changes in time. The Table Filter and Charts for Confluence app will help you to cope with this challenge.

Change History macro

To use the standard mechanism of page versioning in Confluence, insert the Change History macro and get detailed statistics about the requirements specification.

Pro tip:

Learn more about using Spreadsheets in Confluence

Table Filter and Charts for Confluence

As there are a lot of page versions, the Change History table is rather big and not aggregated. To visualize the data, wrap the macro in the Table Transformer, Pivot Table, and Chart from Table macros in succession.

Now you need to configure the macros to get the required result.

Table Transformer

The Table Transformer macro converts the “Mon-DD-YYYY hh:mm” dates to the simple “Mon-DD-YYYY” format. Type in a custom SQL-query “SELECT FORMATDATE(T1.’Published’) AS ‘Date’, * FROM T1” and you’ll be able to group the comments by days later.

You will see the obtained result right in the macro preview.

Pivot Table

The Pivot Table macro helps you to aggregate the comments by types and days. The settings are very intuitive, besides you can always check the macro preview.

Chart from Table

The last step is to visualize the pivot table with the help of the Chart from Table macro. Let’s choose the Stacked Column chart type as it’s shown on the screenshot below.

You get an easy-to-read chart where you can check the number and types of your colleagues’ changes.

The visualization helps you to catch the workflow trend. For example, at the beginning of the project, your teammates mostly worked on the application functionality. Five days later, the number of the Application Reviews decreased, and your co-workers focused on the security issues. The Office Action items reside in every column, so you can be sure that the customer gets all the required documentation on time.

Confluence Cloud

This blog post highlights the requirements management use case for Server and Data Center instances. You can implement the same task for the Cloud version of Confluence as well. The Table Filter and Charts for Confluence app is compatible with all the hosting types.

The steps for Confluence Cloud will be the same, and the only difference is that you’ll need to use the Table Toolbox macro for nesting multiple macros.

How to Aggregate and Reuse Data From Multiple Confluence Tables

June 16, 2020
#How To#Confluence Tutorial#Confluence#Case Study
7 min

Confluence allows you to create informative and well-structured documents to collaborate on. However, despite its sufficient capabilities, some room for improvement of Confluence native features remains. For example, Confluence offers a limited set of formatting tools that is useful when you deal with small tables and can slow down your work with processing table data on large Confluence pages.

Let us say that you need to get specific information from a big table in Confluence, aggregate it somehow, and add a new column. It sounds like too much work to do. Breathe freely – the Table Filter and Charts for Confluence app will automatically perform all the required operations. To prove this point, let’s solve a real use case.

Use case

You have a big Confluence table related to all the departments of your company.

Yesterday you had a meeting that resulted in a kind of a handwritten table with planned sums of overdraft for the locations of your departments.

Now you need to combine these two tables and provide your colleagues with a new table containing locations, their total budgets, and overdrafts.

How to reuse Confluence tables effectively

The simplest way to reuse a big table is to copy it to your page. But here is one significant inconvenience: soon your copied table may become outdated because it isn’t synchronized with the source one.

You can use the Excerpt and Excerpt Include macros to show your big table on another page. When you update the information in the source table wrapped in the Excerpt macro, the Excerpt Include macro automatically reflects the changes. However, if the page contains more than one Excerpt macro, the Excerpt Include macro will display only the contents of the first Excerpt. You can’t use multiple Excerpt macros on the same page.

The best way is to use the Table Excerpt and Table Excerpt Include macros. They allow you to synchronize source and reused tables and recognize multiple Table Excerpt macros on the page.

All you need to do is to wrap the table in the Table Excerpt macro and type in its unique name. The Table Excerpt Include macro creates the reused table. Insert it on your page, select the source for the Excerpt macro (for example, a page with a specified title), and enter the corresponding Excerpt name.

Now the task is fully accomplished, and you are ready to present the results to your colleagues.

Note that this case is just one of many tricky challenges related to Confluence tables and reports, in which the Table Filter and Charts for Confluence app will help you.

5 New Apps to Power Up Confluence – Fourth Quarter 2019

February 13, 2020
#Confluence
10 min

We are ready with our list of fresh Confluence apps released in the fourth quarter of 2019. In this blog post, you will find apps that will help you improve your work with Confluence content and some useful solutions for Confluence administrators:

Let’s take a look at our list of favorites.

Edit Permission Inheritance

When it comes to inherited permissions, Confluence users need to check everything carefully. The thing is that child pages don’t inherit edit restrictions, they only inherit view restrictions. You can restrict access to each page individually but what if you have hundreds of pages you want your users to view but not to edit? The Edit Permission Inheritance app comes in handy.

Now you can easily enable the edit permission inheritance for your Confluence pages with no need to do it manually for each page in the tree. The app will cascade edit restrictions down to child pages making your life easier.

If you need to change the set of permissions on a lower level of the page tree, just define the permission inheritance on the right page. You still can set permissions on any level the way you need it.

This solution doesn’t conflict with Confluence permissions, it copies an existing set of permissions to all child pages helping users to work with page restrictions without difficulties.

Pricing: The pricing for Edit Permission Inheritance for Confluence Server starts from $20 for 25 users and ends at $500 for the unlimited number of users. The pricing for this app for Data Center starts from $4,000/year for 500 users.

Update This+ for Confluence

Update This+ for Confluence keeps track of your content. This app swiftly updates your outdated or archived Confluence pages keeping them live.

If you use Confluence as a knowledge base where your store tons of documentation, this app can be a lifesaver for you because you can refresh even the oldest pages every day. All you need to do is to set the cycle of this add-on to feature the most outdated content every 24 hours starting at 9 am.

Aside from that, this app adds interactivity to your collaboration with colleagues. You can easily check who are the most active contributors in your team and access real-time statistics on total edits. The app displays a countdown timer until the next update sprint cycle to keep your team in the loop.

update this for confluence

Update This+ for Confluence takes your work with content in Confluence to a new level keeping your documentation up-to-date.

Pricing: The Update This+ for Confluence app pricing for Confluence Cloud starts at $20/mo for 20 users and ends at $1,155/mo for 5,000 users.

Easy Heading Free Macro for Confluence

If you want to have the Table of Contents always at hand, Easy Heading Free Macro for Confluence will help you with that. This app adds the floating Table of Contents to your Confluence pages. You can always access this macro on the right of your page and it will appear when you need it.

Moreover, you can collapse and expand headings of your text taking advantage of the floating header.

easy heading for confluence

Plus, you can apply the Easy Heading Macro to all pages across in your Confluence space.

Pricing: Easy Heading Free Macro for Confluence Server is a free app.

Issue Preview for Confluence

Issue Preview for Confluence lets you get more information about your Jira issues right in Confluence. All you need to do is just hover over the issue key.

Now there is no need to switch between Confluence and Jira when you need more information about issues while working in Confluence. This app provides you with a detailed overview at a glance.

issue preview for confluence

Note that you will need a valid license for Issue Preview for Jira to work with this app.

Pricing: Issue Preview for Confluence Server is free to use.

User Deactivator for Confluence

User Deactivator for Confluence is a simple tool that helps you get your user directory in order helping you detect inactive users.

This app allows you to perform bulk operations when you need to deactivate multiple users or remove several users from the group filtering them by the last activity date. You can exclude certain users who are or are not members of the groups you are working with.

Administrators can use this app to disable inactive users based on selected criteria.

Pricing: The pricing for User Deactivator for Confluence Server starts from $10 for 25 users and ends at $5,000 for the unlimited number of users.

 

These were five of the new Confluence apps released in the last quarter of 2019. If you missed our previous list, check out apps that will help you refine your Confluence experience.

If you have any questions, feel free to comment on this blog post below. Don’t forget to subscribe to email notifications about new blog posts in this series!