We rely on cookies to offer our services. By using our Website you permit us the use of cookies in accordance with our policy.



Rome wasn't build in a day - the JWT knowledge base wasn't either

JWT needed a new UI/UI... and so did the docs.

Undoubtedly the Jira Workflow Toolbox 3.0 release was THE biggest UI/UX release we have ever shipped in our history.
While the dev and the product teams were hard at work to  and  the entire user interface (while not breaking the existing extraordinary functionality), the documentation team set out to tame the beast called "product documentation".
The entire process took over a year but we're pretty happy with the results we'd like to share with you.

Searching through the knowledge base

What makes excellent app documentation?

As stated in our previous blog post about the 3 essentials for building awesome Jira workflows

"documentation is frequently the first place users look when they have a question. It is the content for you to help get the most out of the product and the fastest and most effortless path to getting answers".

Here is a recap of the 5 key aspects that define excellent app documentation for us:

  1. It’s extensive.
  2. Information is easy to find.
  3. It's comprehensible.
  4. It's approachable.
  5. It's valid.

Looking at the app documentation state back in 2019, we could check off only 2 of these 5 aspects.

  1. It’s extensive. ✅
  2. Information is easy to find. ⛔
  3. It's comprehensible. ⛔
  4. It's approachable. ⛔
  5. It's valid. ✅

So, on the plus side, we had very extensive and up-to-date documentation! The problem was that most of the information our customers and our team needed daily was condensed on a single page! The expression parser, the heart of JWT, and all its functions were explained on that page in approximately 1,800 lines of text. Not very approachable...

Some information was hidden so deep that even our team couldn't find it even though we generally knew where to look. This had to change, so we decided to completely break up the entire space's structure and re-arrange the content. Looking at the content, we then decided that it had to be mostly re-written since it was very technical and complicated to understand for non-tech users that hadn't graduated in math or physics. 

Structural changes were needed

Instead of having very long pages with tremendous tables, we split up information in smaller chunks, placed it on separate pages, and condensed the information on overview pages using built-in Confluence macros such as the page properties report.


Convert a table..

...with hundreds of expression parser functions

into individual pages...

...listed in a handy page properties macro.

...and provide additional information.

... including use cases in a common format and look&feel.

Making it shine

While restructuring the content, we decided also to visually enhance it. We figured there was no need to make a technical documentation even more challenging to read and understand by simply putting a lot of text out there, which has to be deciphered by the customer.

As always, we started looking at what was out there and (as always) found what we needed to be offered by our friends over at Refined

After we had already restyled our support portals with Refined for Jira | Sites & Themes, we now used their Confluence apps Refined for Confluence | Sites & Themes app in combination with Refined Toolkit for Confluence, which you will find elements of on almost every single page.

Image: Refined

Want some examples?

Let's have a look at just a few places we have used Refined macros.


The Expand macro and UI text boxes...

... to let the user focus on what matters most.

Combining page properties macros and the Refined Tabs macro...

... to get the most out of a single page.




A new landing page

designed with the Content Layout macro and a scrollable and custom-CSS-styled page tree.



Bottom line

An entire cross-functional team was needed to "simply" update a technical documentation to match a new app version. Behind the scenes, hundreds of pages were newly created, excessively updated, replaced, or purged.

To tame the beast, many approaches were being evaluated, tested, and constantly improved. We're not saying that we have found the perfect way to manage such projects in the future, but we have learned a lot. 

And after hundreds of hours of intense and, in parts, repetitive and unrewarding work, the best thing was to look at yet another page properties report and see this:

And yes, this is just an extract. We had about 500 pages in that list.

Share this article



Decadis AG
Viktoriastraße 15
56068 Koblenz

Tel: +49 261 96373 0

E-Mail: info@decadis.de