At K15t, we're kind of nerdy when it comes to documentation. We love documenting things in Confluence and absolutely love helping others create the best documentation possible. So much so that we've built some great apps for creating, managing, and publishing technical documentation in Confluence over the last 10 years.
While solving some of the more complex problems for our customers, we've realized that in many cases, it's actually the smaller things that are points of daily frustration for them.
One such problem is the ability to link different pages. On the surface, this doesn't sound like a problem at all, especially when Confluence does a great job at enabling users to create and manage links between pages. But if we were to look beneath the surface, a few challenges start to appear:
Links are a Two-Way Street
Just adding a link on one page is like a job half-done. For example, let's say you've written an article titled 'Onboarding for New Employees' in Confluence. Now you add some links at the end of the article to other pages that people should read next, e.g. 'How to set up your laptop'. To make this work well, you will need to add a link to the onboarding article as a prerequisite on the 'How to set-up your laptop' page.
These links now need to be maintained on two pages so it's clear on both sides that these pages are related.
Defining the Nature of Links
The nature of the relation between the pages is not clear from just a hyperlink. For example, if you wanted to add a 'Related Articles' section to your page, you will need to manually add a heading and then add links to the pages underneath it. While this works, the relationship is "loosely coupled" – which basically means that the link itself is not aware of the relationship.
Challenges with Exports
When you add hyperlinks to pages in Confluence, they are considered a part of the page content and would be included in exports, which might not be optimal in many cases.
Relation Between a Page and a User
The only kinds of relations that exist between a user and a Confluence today are: Creator and Contributor. But what if you wanted to define an Owner, or a Reviewer? This isn't possible unless you edit the page and '@-mention' these users in the content of the page.
Keeping Track of Updates
Confluence provides some very powerful tools to reuse content across different pages and spaces. But there is no good way to track how changing content on a page will affect all related pages. For example, let's say you've used the Include Page Macro to reuse content from one page in several spaces. From then on, a person editing the source page may not be aware of the impact of the change in other locations.
Taking all of the above challenges into consideration, we really wanted to come up with a valid answer to solve this problem that we – but most importantly, our customers – face every single day.
What it does
With Page Links for Confluence, you can create a network of pages and define the type of relations between them. The app generates pre-defined link types, but users can also create their own name for the page links. Some examples include:
- Next page
- Previous page
- Changes affect
- Is affected by changes in
- Relates to
- Is Related to
Users can also view existing links to ones page grouped by type. This ensures that you never miss the chance to update the right pages of your documentation. Instead of viewing the page links in a separate dialog, it is also possible to add a Page Links macro to the page for a better overview of the network of pages related to it.
Creating recommended reading lists and bookmarks categories of your favorite related pages, and tracking changes across related pages will be a breeze.
How we built it
- The management dialog and the macro use a custom UI built with Atlaskit
- The macro config UI is built with UIkit
- REST API communication with the Relations API is handled via fetch-confluence
Challenges we ran into
- No support for custom macro icons in Forge right now.
- Automatic resizing of custom UI dialog doesn't seem to work reliably
Accomplishments that we're proud of
- Building a production-ready app in such a short time complete with a getting started video and documentation.
- Working with a cross-functional team where no one had prior knowledge of Forge.
What we learned
- Development flow using forge
- Deploy an app with forge to production and share it with others
- Use forge UI kit to create confluence extensions
- Forge manifest scopes and permissions
- At this point, we will benefit more by using Custom UI.
What's next for Page Links for Confluence
- We will upload the app to the Atlassian Marketplace and distribute it for free.
Here are some features we would like to prioritize -
- User-defined custom link types
- Link other resources to a page (Jira issues, Bitbucket branches, Weblinks, ...)