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.

Connecting Sharepoint and Atlassian Confluence together

February 18, 2021
#How To#Confluence
6 min

Did you know that switching between different systems and apps is not only annoying but costs businesses hundreds of billions of dollars annually due to wasted time? Enabling users to immediately find the information they are looking for is crucial to empower efficient teamwork.

Let us imagine you want to create an overview of an upcoming marketing campaign in your Confluence. Having all information and documents available on this specific page helps all employees, from marketing to sales, to get what they’re searching for with ease. But how do you accomplish such a comprehensive overview?

SharePoint Connector for Confluence

Communardo’s SharePoint Connector for Confluence is here to help! By integrating Confluence and SharePoint, you enable a seamless work experience and get the best out of both worlds. The app makes it possible to easily embed SharePoint content into Confluence.

Using the SharePoint document macro, you can either embed full-views or links of SharePoint documents as simple as posting the document URL. In case you got many files to share, you can even choose to embed a whole SharePoint document library. Now your colleagues can easily edit documents without the need to navigate to SharePoint first.

The SharePoint Connector for Confluence is available for all Atlassian hosting options (Cloud, Data Center, Server), as well as SharePoint Online (as part of Microsoft 365/Office 365) and on Premise (2016, 2019).

» Start my free trial of SharePoint Connector for Confluence

Smart Attachments for Confluence

If once you decide to finally migrate your document library from Sharepoint to Confluence, the Smart Attachments for Confluence app is the first option to consider. It integrates with Confluence and allows you to create local file storages within your Confluence spaces.

For those of you who migrate from Sharepoint, you can just drop all your existing folders with files and internal folder structure, and the app will recreate this structure from scratch. So that you can preserve all your folder structures and files as you have them in your Sharepoint.

You can perform all the basic operations on folders and documents, keep document revisions, manage labels, or move them between folders of yours. What stands this app from others is that it closely integrates with Confluence itself, so as a result, you can preview all the files and documents, edit them with Atlassian Companion, embed them into Confluence pages, and, of course, comment on them. This greatly simplifies the end-user experience and reduces the number of context switches, which leads to better productivity of your team.

By default, the file storage is available to all Confluence users, and the availability of specific features is regulated by space permissions, so you needn’t adjust anything in your access control policies and go as is. The app also lets you perform non-trivial tasks, such as:

  • lock a specific document against edits while you are editing or reviewing it
  • restrict access to folders with sensitive information
  • share a folder with documents with some external users who do not have regular access to your Confluence, for example, when sharing assets with your customers.

To minimize the necessity to constantly switch to the file storage, you can embed specific folder structures into Confluence pages. This way, you can instantly view, edit, and upload documents from your Confluence pages without losing your current page context or interrupting your activities.

» Start my free trial of Smart Attachments for Confluence

Bring Sharepoint capabilities into Confluence

It is no longer a problem to show Sharepoint content in Confluence. As of now, you can consider two options:

Which option to choose? Try both options and then decide which better fits your needs. Have any questions? Leave your comment and we will reply to you shortly.

How to Improve Team’s Workflow with Dynamic Statuses in Confluence

October 6, 2020
#Task Management#How To#Confluence#Case Study
10 min

I would highly recommend Handy Macros for Confluence to any company (in any industry), which is looking to standardize and streamline their work management process and automate the generation of data to evaluate individual and team performance.

Michael W, Senior Engineer at DENSO

This blog post is a case study one of our customers helped us write. Michael W, Senior Engineer at DENSO, described how their team uses Atlassian Confluence in a bundle with our Handy Macros for Confluence app to deliver better work faster.

*This case study contains the screenshots we created based on our customer’s information. We do not show you DENSO’s Confluence pages for privacy reasons.

DENSO is the second largest advanced automotive technology supplier in the world, developing a wide range of products and systems for car manufacturers and the global mobility industry. DENSO technologies can be found in several automotive systems, including Powertrain, Thermal, Safety and cockpit, and In-car entertainment. So if you see a vehicle on the road, chances are there is a DENSO component powering it or optimizing it in some way.

With over 200 companies worldwide, DENSO leverages its strengths in R&D and manufacturing to accelerate the development of connected, autonomous, shared, and electrified (CASE) mobility, with a primary focus on safety and the highest level of quality.

Performance evaluation in Confluence

The DENSO team uses Confluence to get everyone on the same page. This collaboration software allows them to stay focused on their tasks, boost overall employee alignment. and measure individual and team performance,

They developed their task tracking system right in Confluence using Page Properties and Page Properties Report macros. Each task contains information on its type, status, deadline, owner, etc. In the process of working on a task, the team usually needs to change the information about task status and the requester.

Advantages they found using Confluence workload tracking:

  1. Quantitative monitoring of their work output against deadlines.
  2. Easy generation of accurate KPI output based on the information from their reports.
  3. Update of the status from the summary view.

It also became possible after the installation of Handy Macros for Confluence. This app helped their management to succeed in communicating team output and achievements against their KPIs to their senior management and directors.

Interactive statuses for better task management

Handy Status is a macro the EU wide diesel powertrain group of DENSO uses most for speeding up data entry compared to a manual typing. The user-friendly interface of this macro makes it easy to use. The team creates different status sets depending on their needs to prevent mistakes or inconsistencies in data entry across team members.

They take advantage of the Handy Status drop-down selection because it helps them generate automated tags. These tags allow them to create tracking tables and specific summary pages. Moreover, the team can collect data and display it against their business KPIs. They also create their set of statuses per space, adding them to the tables in the Page Properties macro.

This system helps them track work according to any number of inputs (team/individual/customer/priority), making overall work management much more effective. 

The team can change any status right in the view mode of the page.

They use the Handy Status macro to define all members of the team. Since they have a lot of people to choose from, we’ve added the capability to filter their names on the fly. So in case, there are more than 15 items in a set, a user starts typing the colleague’s name and selects the required one from the list.

The list of all users

The great thing is that when users hover over any status, they can rapidly track the status change history.

Status change history

Powerful custom reports

The team can use the information from the Page Property Report macro for building reports and tracking tables depending on their needs.

Users can easily modify summary tables getting live updates from the source pages.

Now all levels of DENSO’s engineering and management staff use this system from graduate-level positions up to the director level in their EU wide diesel powertrain group. They also plan to use it in the future across their group companies in the EU, North America, and Asia.

The primary benefit for DENSO as a company is the fact that Handy Macros for Confluence has allowed them to implement an automated system of work management, standardize it, and made it much easier for their senior management level to accurately track and understand the team output. This has become more important as the size of the group being managed has increased both in size but also across many different offices in different countries.

You can discover 11 more macros that are available in the Handy Macros app.

Try Handy Macros for Confluence for free. This app is also available for Confluence Cloud and Data Center.

How to Power up Page Properties Report in Atlassian Confluence

July 17, 2020
#Document management#Reporting#How To#Confluence Tutorial#Confluence
2 min

We’ve recorded this presentation for the online Team Up Forum hosted by k15t and Scandio.

Discover how to power up the Page Properties Report macro with the help of two apps:

You can easily filter and aggregate information on Confluence pages. Moreover, you can create your set of statuses and change them in the page view mode on the fly.

Discover our comprehensive list of apps to boost your project planning capabilities here!

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

5 New Confluence Apps to Work Better Together – First Quarter 2020

May 8, 2020
9 min

Atlassian vendors are doing their best to enhance our Confluence experience with new apps. We are checking what’s new on the Atlassian Marketplace every three months. This time we prepared a batch of fresh Confluence solutions that will help your team work better together.

Here is our list of the most interesting apps released between January 1st and March 31st:

Let’s take a closer look at each of them.

Metadata for Confluence Cloud

Metadata for Confluence Cloud is a nifty add-on for Atlassian users who miss some Server features in Confluence Cloud. This app allows you to organize and manage your content with the help of custom fields and macros. If you have a lot of Confluence pages, you can easily classify them and create page reports. You just need to configure metadata fields to keep track of your pages.

metadata in Confluence

Your colleagues will use the predefined page structure.

You can also use built-in macros if you want to display the metadata on your page, or you need to aggregate data from different pages. You can either show the metadata on a page or view a summary of multiple pages.

This solution will help your team not to get lost among thousands of Confluence pages.

Pricing: The Metadata for Confluence Cloud app pricing for Confluence Cloud starts at $10/mo for 20 users and ends at $1,535/mo for 5,000 users.

Image search for Confluence

It can be challenging to find some information in Confluence. And it seems almost impossible to find an image. Image search for Confluence comes to the rescue. The best thing is that you can search for both images and thumbnails.

This app adds the Image tab to the search, and you just need to start typing the name of the file you are searching for. Moreover, you will have a preview of all images that match your search query, and you can filter the results by space, creator, and date.

This way, you can find the required Confluence page because search results are linked to the pages your images are attached to.

Use this app to make your Confluence search smarter.

PricingThe pricing for Image search for Confluence Server starts from $75 for 25 users and ends at $4,200 for the unlimited number of users. 

Group Ambassadors for Confluence

Confluence administrators can delegate group management to the users they choose with the help of the Group Ambassadors for Confluence app. This way, the nominated group ambassadors can manage Confluence groups without administrative privileges.

Group ambassadors become group managers and can browse their current groups as members, rapidly add and remove users. However, administrators can restrict browsing in some groups ambassadors can see. These privileges can be granted and revoked easily. Administrators can check the list of current ambassadors in a blink of an eye.

This app is also available for Jira. Administrators can focus on their tasks, delegating group management to their colleagues.

PricingThe pricing for Group Ambassadors for Confluence Server starts from $140 for 25 users and ends at $8,000 for the unlimited number of users. The pricing for this app for Data Center starts from $1,250/year for 500 users.

Team Decision for Confluence

Today, we use a lot of messengers and tools to communicate with our teammates. We need to discuss so many things about our work and team-building activities and, of course, make crucial decisions.

Team Decision for Confluence is a handy solution that you can use for voting, gathering your team’s opinions right in Confluence. This app allows you to create simple polls right of different types:

  • Proposal
  • Check
  • Poll
  • Dot Vote
  • Score Poll
  • Time Poll
  • Ranked Choice

Decision for Confluence

The great thing is that detailed results of any poll are available in Confluence that helps you make decisions together with your teammates faster and smarter. You can rapidly review and respond to these decisions.

This app helps you avoid multiple emails and nerve-racking meeting when you need to find common ground with your team.

Pricing: The Team Decision for Confluence app pricing for Cloud starts at $10/mo for 20 users and ends at $570/mo for 5,000 users.

HTML include macro for Confluence Cloud

HTML include macro for Confluence Cloud allows you to include and embed different types of HTML content right into your Confluence pages. With the help of this app, you can add custom HTML and Javascript code to your pages.

Moreover, you can create content with videos, various forms, and surveys.

This simple app helps you create informative, useful content in Confluence.

Pricing: The HTML include macro for Confluence Cloud app pricing for Cloud starts at $10/mo for 20 users and ends at $570/mo for 5,000 users.

These were five of the new Confluence apps released in the first quarter of 2020. If you missed our previous list, check out apps that will help you power up your Confluence.

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!

5 New Confluence Apps to Refine Confluence Experience – Third Quarter 2019

December 13, 2019
9 min

As we do every quarter, we present you with the five new Confluence apps we like most. We have created this list to help you discover apps that will increase your productivity at work.

So let’s discuss each app in more detail and see some examples of how you can benefit from using these solutions.

New meeting experience for Confluence

Meetical Meetings for Confluence helps you sync your events in calendars with your Confluence pages. You can easily prepare and hold meetings, so your team always knows what’s next. So how does it work?

Confluence page will be created based on your event in Google Calendar and the link to the event will be automatically added to the event description. If you decide to change anything, this information will be automatically updated in Confluence. This app allows you to track the attendance status of your colleagues right in Confluence.

This app groups recurring meetings and creates a parent report page keeping you up-to-date with all important events. This means that the overview of all your meetings is always at hand in Confluence. You just need to click the Meetings tab on the Confluence menu.

Use this solution to effortlessly schedule meetings with your teammates.

Pricing: Meetical Meetings for Confluence Server is free to use.

Version control for Confluence templates

Page Templates Change History Control provides Confluence with a version control feature for templates. Now you can monitor and control changes of page templates in any Confluence space and Global page templates.

You can access the required information on a space level in the Space tools menu to have a detailed overview of page template history. You can also access the Global Templates History tab in the administration menu. In both cases, you will see the list of available templates. You can see the history of changes for each template in more detail: view the body of any template version, restore any version, or delete it.

This app allows you to quickly get information about users who made changes, check when they did it, and view additional information.

Pricing: The pricing for Page Templates Change History Control Server starts from $15 for 25 users and ends at $500 for the unlimited number of users.

Multi-level navigation in Confluence

Navigator for Confluence allows you to populate the Confluence header with useful links to your top-visited or work-related sites. You can create a multi-level structure and rapidly group the required links.

After installation of this app, visit the administration page to configure it properly. You can add as many items to the menu as you need; in this case, parent tabs are not clickable.

Pricing: The pricing for Navigator for Confluence Server starts from $95 for 25 users and ends at $1,770 for the unlimited number of users.

Powerful search for Confluence

iFinder Universal Search for Confluence takes the search capability of Confluence to the next level. With this app, you will find the content you are looking for because it doesn’t just search within Confluence. You can connect various tools you are using internally (like file shares, Jira, SharePoint, Office 365, and more)  to Confluence. In this case, the app will also search within these applications.

The app indexes Confluence spaces, pages, blog posts, comments and attachments including their access rights for later full-text search. Users can only access information in accordance with their user roles and rights.

iFinder provides users with a powerful searchbar that autocorrects and autocompletes your quires. This app allows you to view and informative list with your search results with highlights, useful filters, search tabs.

You can use this solution to power up your Confluence and make your search experience more pleasant.

Pricing: The pricing for iFinder Universal Search for Confluence for Data Center starts from $4,000/year for 500 users.

Highlights for your Confluence pages

vSearchHighlighter is a simple tool that highlights the word you are searching for within the page. This app provides users with a simpler and more powerful search experience in Confluence. When you search for something in Confluence, you need to choose the required Confluence page in the search results and the app highlights every occurrence of the search term within the page.

It can be useful when you need to edit a long page in Confluence, you can easily find specific terms.

This app enhances your search experience when you need to find any information in Confluence.

Pricing: The pricing for vSearchHighlighter Server starts from $57 for 25 users and ends at $1,062 for the unlimited number of users.

We hope that you will find all these solutions useful for your team and reveal their potential for getting work done most productively and effectively.

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!