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.

Case Study: How a FinTech Company Improves Code Review Process

June 30, 2020
#Case Study#Bitbucket
8 min

We’ve got pretty good with our Pull Request and Code Review process, but initially, our PRs were complex, not very well documented, and difficult to read. The Resolution Time Distribution graph shows how better we are getting at this, being able to merge PRs much quicker than before.

Pablo Reyes, VP Engineering at Strands

Strands is one of our customers that has been using Awesome Graphs for Bitbucket for a couple of years so far. Since 2004, Strands has been developing highly customizable digital money management software for top-tier financial institutions worldwide. Our team is happy to help them reach their goals and improve their development processes with the statistics visualizations we provide.

Pablo Reyes, VP Engineering at Strands, agreed to share how their team uses our solution and provided us with a picture of how they:

  • identified bottlenecks in code review
  • tracked if this process was improving with the changes they implemented
  • increased developers’ motivation watching the trends in individual performance.

Code review process improvement

In fact, they’ve got pretty good with their Code Review process so far. But initially, the PRs were complex, not very well documented, and difficult to read. The Resolution Time Distribution report shows how better they are getting at this, merging PRs much quicker than before. code review process improvement in Bitbucket

Since they do a lot of code reviews at Strands, it’s always nice to see who and what teams are making the best use of it. It’s encouraging for the team to see the progress with these reviews, and the Pull Requests reports give them the perfect overview of these improvements.

A couple of years ago, they started improving their methodology. For example, introduced the practice of approving PRs by at least three people. Moreover, they also encouraged developers to leave lots of comments and suggestions and not approve a PR until it’s good enough.

PRs are resolved faster now because they are done better, and the quality of suggested things improves all the time. As a result, it’s nice to see how senior developers make sure everything is done according to coding guidelines. Overview of how things are going and if it improves or not is presented in the Contributions report.

contributions report in Bitbucket

Coding trends

At Strands, managers don’t use Awesome Graphs to control the number of commits per developer, but they find it useful to look at the dynamics of the overall activity to capture the trends. For example, if there’s a significant drop, the developer is probably stuck at some difficult tasks or disturbed by various activities, helping other teams or communicating with customers.

Most things are caught soon in the day-to-day communication and work, but mid-term changes in the trend (either a decrease or increase) give them a hint of something they may need to look at. This has been visible when people change projects or teams.

The Developer’s Contributions graph gives a clear view of this kind of drops and rises, and it’s handy to compare two periods before and after certain changes were implemented.

developer contributions in Bitbucket

Any trend is a good point to discuss and find if there’re any bottlenecks or places to be improved with the processes in a team. Performance is a complex measure and depends on lots of different things, some quantitative and some qualitative, but the aggregation of code contributions (comments, pull requests, tasks solved, commits, etc) gives some good indicators on how a team is evolving with time.

Along with the others, the Contributors graph provides this kind of insight into the dynamics of code contributions by different teams.

code contributions by different teams

Try the best teams’ practices for your company

Awesome Graphs for Bitbucket has become a useful tool for Strands on their way of identifying where the problematic places are, and tracking if the implemented changes improve the situation or not. Besides, it appeared to be a handy instrument for regular monitoring.

Try Awesome Graphs for Bitbucket for free and check if it can help you as well.

Read more case studies to see how our customers benefit from using Awesome Graphs for Bitbucket in their work:

Remote Teams Management: How to Turn Data into Code Review Insights

March 17, 2020
#How To#Bitbucket#Reporting#Analytics
12 min

Leading remote and distributed teams can be quite challenging. Distance makes it more difficult to monitor your team activity. So, you have to either rely on them, hoping it won’t end up as a disaster, or annoy developers with overcontrol.

Fortunately, there’s no need to go blindly as you can go data-driven and use the statistics of developers’ activity to your advantage.

In this article, we focus on pull requests metrics as a way to identify bottlenecks in the code review process and check if it’s healthy or not. You will find the answers to the following questions:

  • What metrics to choose as a subject to analyze and how to organize them.
  • How to retrieve them using Bitbucket REST API.
  • How to interpret metrics to get as many insights as possible.

Pull Requests status dashboard

If you want to keep in touch with the pull requests on your project status, you may find it useful to create a dashboard that visualizes the statuses of pull requests. This helps you see:

  • the number of pull requests your team created for the last week/month/sprint
  • how many pull requests are already merged and which of them are still open
  • if there are any pull requests open long ago and are not merged yet.

You can retrieve this data using this Bitbucket REST API request:

https://your-bitbucket-url/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests?state=all

Get the following information from the returned results: pull request ID, state, and the date it was created and merged in the Unix time format.

{
    "size": 25,
    "limit": 25,
    "isLastPage": false,
    "values": [
        {
            "id": 13,
            "version": 13,
            "title": "Looking for Sarah Connor",
            "description": "Trying to save the Future",
            "state": "MERGED",
            "open": false,
            "closed": true,
            "createdDate": 1583837364846,
            "updatedDate": 1583843660283,
            "closedDate": 1583843660283,
            "fromRef": {},
            "toRef": {},
            "locked": false,
            "author": {
                "user": {
                    "name": "arnie",
                    "emailAddress": "arnie@stiltsoft.com",
                    "id": 3,
                    "displayName": "Arnie",
                    "active": true,
                    "slug": "arnie",
                    "type": "NORMAL",
                    "links": {},
                "role": "AUTHOR",
                "approved": false,
                "status": "UNAPPROVED"
            },
            "reviewers": [
                {
                    "user": {
                        "name": "sarahconnor",
                        "emailAddress": "sarahconnor@stiltsoft.com",
                        "id": 4,
                        "displayName": "Sarah Connor",
                        "active": true,
                        "slug": "sarahconnor",
                        "type": "NORMAL",
                        "links": {},
                    "lastReviewedCommit": "",
                    "role": "REVIEWER",
                    "approved": true,
                    "status": "APPROVED"
                }
            ],
            "participants": [],
            "properties": {
                "resolvedTaskCount": 3,
                "commentCount": 1,
                "openTaskCount": 0
            },
            "links": {}
                ]
            }
        },

Then create a script that parses these data and turns it into a pull requests status dashboard. 

There are some possible difficulties you may face due to the REST API restrictions:

  • The number of returned results is limited, so you’ll have to make several requests to retrieve all data.
  • It’s only possible to run the query on a repository level, so the more repositories you have, the more requests you’ll need to make.
  • The Bitbucket performance may be affected in large instances.

The same can be done using the Pie Chart report in Awesome Graphs for Bitbucket. Grouped by state, it shows the number of pull requests created during the chosen time span with their current statuses. 

Tip: find pull requests created long ago and not merged yet by selecting a previous week or month as a period to analyze.

Reviewers’ involvement

Another pattern to watch is whether all team members participate in the code review. If not, there are some possible consequences:

  • knowledge sharing in a team is poor, and junior developers miss the opportunity to grow their skills without watching the examples of more experienced programmers’ work
  • pull requests resolution may be slow if there are more pull requests created than people who can review it
  • those who review all pull requests may have no time to write new code.

The same REST API request from the previous paragraph retrieves the data about the participants of pull requests. Organize these data as a list of reviewers and the number of pull requests they reviewed to get insights about the developers’ involvement in the peer review. 

The Pie Chart report grouped by reviewer serves the same purposes and gives you a breakdown of pull requests reviewed by all members of your team.

Tip: pay attention to pull requests that are merged without reviewing. Those are the areas where you may have a risk as the code was not checked as appropriate. 

Reviewers’ activity chart

The difference between just being assigned as a reviewer and truly reviewing the new code and suggesting improvements to it is huge. Luckily, there are a couple of metrics to watch that may help you get a clear view of the thoroughness with which developers check each other’s work.

Use this REST API request and retrieve the data about the number of tasks, comments, needs work, or approved actions per pull request and group it by user:

https://your-bitbucket-url/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/activities

The example of the returned results with the data that needs to be parsed:

{
    "size": 5,
    "limit": 25,
    "isLastPage": true,
    "values": [
        {
            "id": 46766,
            "createdDate": 1574762295000,
            "user": {
                "name": "sarahconnor",
                "emailAddress": "sarahconnor@stiltsoft.com",
                "id": 3,
                "displayName": "Sarah Connor",
                "active": true,
                "slug": "sarahconnor",
                "type": "NORMAL",
                "links": {}
            },
            "action": "MERGED",
            "commit": {}
        },
        {
            "id": 46756,
            "createdDate": 1574690608000,
            "user": {
                "name": "johnconnor",
                "emailAddress": "johnconnor@stiltsoft.com",
                "id": 652,
                "displayName": "John Connor",
                "active": true,
                "slug": "johnconnor",
                "type": "NORMAL",
                "links": {}
            },
            "action": "APPROVED"
        },
        {
            "id": 46688,
            "createdDate": 1574431693000,
            "user": {
                "name": "arnie",
                "emailAddress": "arnie@stiltsoft.com",
                "id": 4,
                "displayName": "Arnie",
                "active": true,
                "slug": "arnie",
                "type": "NORMAL",
                "links": {}
            },
            "action": "COMMENTED",
            "commentAction": "ADDED",
            "comment": {
                "properties": {},
                "id": 6569,
                "version": 0,
                "text": "i need your jacket, boots, and motorcycle",
                "author": {}
                },
        {
            "id": 46668,
            "createdDate": 1574418254000,
            "user": {
                "name": "sarahconnor",
                "emailAddress": "sarahconnor@stiltsoft.com",
                "id": 3,
                "displayName": "Sarah Connor",
                "active": true,
                "slug": "sarahconnor",
                "type": "NORMAL",
                "links": {}
            },
            "action": "OPENED"
        }
    ],
    "start": 0
}

The visualization of the developers’ activity in pull requests provides you with the following insights:

  • Most active reviewers in your team. These people check the code thoroughly. On the other hand, this pattern may have negative sides if the perfectionism slows down the feature delivery too much.
  • Infrequent participants in the code review. These developers are not involved in the knowledge sharing process for some reason. Do they skip this part of work intentionally, or are they afraid to criticize their colleagues’ work? 
  • Periods with unusual activity. Check the values that go beyond the trend to find the answer to why the reviewer had to leave too many or too little comments. For example, there can be bad code or the pull request was too large, and nobody wanted to check it. These are the patterns that you’d definitely like to avoid.

The Contributions report provides the same view across projects and repositories with the swift access to each pull request in Bitbucket so you could check its content.

Tip: group this report by author to see who receives the largest number of tasks and comments in their pull requests. This may be a sign of a code that took lots of re-writing and may lead to bugs in the future. Besides, looking at the dynamics of these numbers makes it obvious if developers are improving their working patterns or not.

Try the data-driven approach to bring transparency into your code review processes

Tracking developers’ activity may be especially important in remote or distributed teams where it’s impossible to reach each other physically. 

However, the benefits that metrics bring are valuable for any company as they help:

  • find areas to improve in code review processes
  • optimize peer review practices
  • avoid slowdowns and poor quality code. 

Create your dashboard using the Bitbucket REST API or try Awesome Graphs for Bitbucket for free to discover how you can benefit from it!

Introducing New Feature: Graphs for Teams in Awesome Graphs

December 3, 2019
#Bitbucket#Reporting#Analytics#News
7 min

There is no doubt that effective working and communication processes in a team greatly influence the overall success of a product or company. Atlassian products like Bitbucket, Jira, and Confluence aim to improve collaboration and bring distributed colleagues together.

Awesome Graphs for Bitbucket app is our contribution to the teamwork of more than 2,000 companies, as its primary goal is to help identify the bottlenecks in the development workflow and increase the speed. We are eager to make the processes transparent for both developers and managers and, thereby, improve the communication and narrow the gap between them.

We’ve discovered that lots of our clients use similar workflows: they have multiple teams working on the same project or repository. Therefore, tracking the productivity of a particular group that a project or delivery manager, or team lead manages can be tricky as the app showed graphs for all the activity across a project or repository that included the statistics about all the teams together. That’s why we decided to implement a feature that can make their lives easier: graphs for teams.

View the statistics for your team

Teams feature is designed to visualize the statistics about your team performance if there’s a lot of people working on a project or repository. It excludes the contributions of the members of other teams and helps get rid of noisy data.

Configure your teams in the settings and choose it in the All contributors drop-down menu on the Graphs page and analyze how much commits, pull requests, and lines of code a team produces apart from others.

Compare the activity of different teams

If you manage multiple teams working on the same project or repository, you may find it useful to separate their statistics from each other.  For example, compare their impact in a codebase of your repository using the Code Frequency graph. That’s what you can easily do with our new feature!

Let’s say you manage two teams: back-end and front-end developers. Open a graph for each team in different tabs and compare their performance.

From the screenshot below, you may identify that your back-end team is continuously deleting the lines of code. They are probably involved in some bug fixing or refactoring activities or implement changes in the API.

Meanwhile, the front-end team has to rewrite some pieces of code to adjust the changes in the backend.

Exclude automated users from the statistics

If you use automation in your repositories, the graphs may show the information that is not related to the activity of your team. Lots of commits and lines of code added by CI/CD users and automated scripts may complicate the performance analysis since it’s not obvious which contributions are made by real people and which of them are not.

Use teams feature to solve this problem by creating a team with all the people you need except for the automated users.

Teams management

A team can be made on the global, project, and repository level by the user with administrative permissions on this level. A team can include whole Bitbucket groups or individual users.

It’s possible to create a global team in the Teams tab in the Administration page and view graphs for it in all projects and repositories.

There’s no need to disturb your Sys Admins from their work to create a team. If you’re a project or repository admin, you may do it in the Teams tab in the settings. In this case, your teams’ graphs will be available only in your repository or project and higher.

Improve your teams’ activity tracking

At the moment, graphs for teams are available only for the Graphs page, but we’ll add this feature to the People page and Reports soon in the next releases.

Try a new version of Awesome Graphs for Bitbucket to get even more useful insights on your team productivity and compare the activities of different teams!

We are delighted to implement the team feature that our customers were asking for, and we hope to make their working process a bit easier and better! So, we appreciate any feedback on the app and suggestions that could help you get the most benefit from Awesome Graphs. If you have any, please, feel free to write to us here as we’re looking forward to learning about your needs!

How to Easily Adjust Templates in Atlassian Confluence

August 15, 2019
#How To#Confluence#Case Study
9 min

In its 15 years of existence, Confluence has become one of the leading solutions for building knowledge bases and creating documentation together with your team. However, a lot of companies are still getting used to the new software after migration and a lot of organizations that use Atlassian products still hire new employees without Confluence experience.

Naturally, novice Confluence users have lots of questions about the new software:

  • How to create required documents and format their content?
  • How to protect sensitive data and share public information?
  • How to organize meetings and discuss projects?

You can use various Confluence features to achieve your goals and automate everyday routine tasks. But sometimes it is not obvious for novice Confluence users what tools to choose for this or that case. So, they reach out to more experienced colleagues or may post questions on the Atlassian Community. For example, we’ve recently found a lot of questions about Confluence templates there.

Atlassian community questions

A template is one of the most useful Confluence features that can significantly ease your working life. After reading this blog post, you will be able to use templates freely.

Use case: creating and managing release notes

Imagine that you work in a software company that uses Confluence on a regular basis. Your department has a real disaster with its release notes pages. Everybody creates them chaotically at different levels of the space page tree. Besides, your colleagues use their own page structures and decide what information to add themselves. Every page looks differently. The users also give various page titles and forget to add labels. So, it is rather difficult to find the required data.

Let’s use Confluence templates and deal with this mess together.

What is a template?

A template is a Confluence page with predefined content. There are two kinds of templates:

  • Global templates that are available in every space of your corporate Confluence site. These templates are defined by your Confluence administrator.
  • Space templates that are used in a specific space. Space templates are defined by space administrators.

Why do you need templates?

You can create new pages based on templates and save your time on content formatting. Just click the “Create from template” button and choose the required item. Let it be the standard “Meeting notes” template.

Jira templates

Now you can follow the instructional text and fill out the required fields of your document. Note that all instructional text disappears as you type in your own information. You also can’t see instructional text while viewing a page.

Meeting notes template

When you create a page from a standard built-in Confluence template for the first time in a space, a new shortcut and an index page will be created. Space shortcuts allow you to access your pages quickly and easily. The index page displays a list of pages based on this template and certain summarized information about them.

meeting notes in Confluence

Here is an example of the “Meeting notes” index page:

Meeting notes index page

Where can you find templates?

If you have the Space admin permission, go to the Space tools menu and find the Content tools → Templates. Here you can see all the space templates: built-in and customized (created by the space administrators).

Confluence space templates

What can you do with templates?

You can easily adjust Confluence templates for your needs:

  • Promote a template if you want your colleagues to pay attention to it and begin to use it constantly. All other templates will be hidden under the Show more linkIf someone uses the Show more link more than three times in a single space, the dialog will show you all the templates by default from then on.

Promoted template in Confluence

  • Edit an existing template to customize it: add and delete macros, variables, tables, labels, images, and instructional text. Work with your template like with any other Confluence page. The only difference is that you can’t upload images or attachments directly to your template, but you can find them on other pages. Having a special page as a resource library for these types of things is recommended.
  • Create new templates if you have any specific corporate documents that you want to use in Confluence.
  • Delete/disable a template if you don’t want it to be available in this space.

Note that you can use page templates only when you add a page. It is not possible to apply a template to an existing page.

Let’s resolve your case

Now that we are done with the theory, let’s return to your task.

Step 1. Design your own template

As there are no any built-in “Release notes” Confluence templates, you need to create your own new template. Feel free to use instructional text and don’t forget to add labels if you want to assign them automatically.

To add instructional text go to the Template menu of your toolbar and choose the corresponding item.

Create release notes template in Confluence

Step 2. Share your template with the team

Now you need to show your colleagues that the “Release notes” template exists. You can just promote it.

Promoted release notes template

Step 3. Get your page tree organized

Now you need to organize all your future release notes pages within the space. Create a new parent page for them and add the “Create from template” macro to it. Edit the macro body as it’s shown in the slide below: choose your new template and customize page titles. Now your colleagues can easily create release notes pages directly from this parent page. 

Create from template macro

Check the results

From now on the release notes pages will have the same structure, titles, labels, and parent page. Your space will be organized neatly, and it will be much easier to find relevant content.

Confluence templates

How to quickly learn all Confluence features?

If you want to know more about real-life challenges in Confluence, take our free Quick Start with Confluence training course.

Our motto is “one use case, one module”. You’ll learn everything you need for the case in the corresponding lesson and boost your productivity immediately.

How to Perform Code Review and Track Team Activity in Bitbucket

August 8, 2019
#How To#Bitbucket#Case Study
6 min

Resolution Time Distribution Reports have helped a lot during the development of a high priority module to increase the reviewers, review frequency and also track team activity in Bitbucket.

Eduard Pal, Innoface

Innoface GmbH, one of our customers, is one of the leading providers of interfaces between PDM and ERP systems worldwide. Its applications help ensure a direct and reliable flow of information between engineering and logistics. They also offer additional products and services in order to facilitate seamless integration of the involved systems.

Innoface product development team uses Awesome Graphs for Bitbucket mostly for making data-driven management decisions. They find it very useful to:

  • track the activity of each developer and a team in general;
  • check if code review goes according to the plans;
  • predict time to resolve pull requests.

Let’s see how Innoface benefits from using Awesome Graphs for Bitbucket.

Tracking team activity in Bitbucket

Activity graph helps Innoface have a high-level overview of the total number of commits and contributors in a specific period, for example, a week. It also provides an opportunity to track the number of open pull requests from all the contributors and the repositories.

Using this graph, the manager can assess the activeness of a contributor. This gives the manager an idea of whether an employee is following the company’s development policy or not as well.

tracking team activity in Bitbucket

Based on the number of open pull requests, the manager in Innoface can actually plan time to review the code and merge them. This graph also gives an opportunity to process the pull requests from the contributors that are working on the high-priority projects.

Analyzing code review practices

Innoface management finds Resolution Time Report very helpful when it comes to tracking the frequency of processing the pull requests.

analyze code review in Bitbcuket

The manager uses this report in order to see the frequency with which the reviewers are processing the pull requests. Based on the data that this report provides, it’s easier to make a reasonable decision and to assign either more reviewers or increase the frequency of the reviewers, especially for the high-priority projects.

Predicting pull requests resolution time

Resolution Time Distribution report helps Innoface estimate resolution time for future pull requests to make more accurate release dates planning.

pull request resolution time in Bitbucket

The manager of a product team uses this report in addition to the Resolution Time Report in order to estimate the resolution time for future pull requests.

Conclusion

Awesome Graphs greatly enriches the Bitbucket user experience for Innoface. With its help, it becomes much easier to make decisions based on data and keep an eye on how efficient their development practices are.

Read more case studies to see how our customers benefit from using Awesome Graphs for Bitbucket in their work:

Start a free trial of Awesome Graphs