Exporting huge tables from Confluence? Go condensed

Not all pages are created equal. Some are quick news updates- read them in a blink and move on. Some are investors briefing- every line is inspected and digested. And then, some are technical specifications. These are all important but never read from start to end. These differences are crucial if you need to export Confluence pages.

Because when exporting a page from Confluence, each page may require its own layout. A unique format to shine.

I work with many teams on their technical specifications. Specifications often are exported from Confluence and shared with third parties, like customers and regulatory inspectors. We’ll share best practices that yield great Confluence pages, that export beautifully- to the delight of any external reader.

You have nailed how you create specification documents. You manage the specification items in Jira. Each item is a requirement issue or a story. From all these issues, you need to create release documents. The easiest way to do this is to use Jira Snapshots for Confluence .

The most complex specification document is the traceability report. It shows the high level specifications, how they are linked to other elements in the specification hierarchy: design specifications, tests, and test results.

Traceability tables tend to be very wide, and very long.Like hundreds or thousands of pages long.

Just recently I helped generate a report like this. Once exported from Confluence it was around 1000 pages long. Even though we no longer print these on paper, we wanted to get the number of pages down. The way the data was on the table, we had too much white space in the document and too much scrolling to do.

The gist of the challenge is this:

How to export a Confluence page that has a huge table, so that:

• The exported file will be pleasing to the eye, especially when viewed on a screen.
• Not look like there is white spaces everyone and too much “spread”. Minimise scrolling.
• Each row will be easy to read.

After working with many pages like these to create release documentation, here is my recipe for creating the perfect exports. It works the same for Cloud and Data Center.

Install the Apps to optimise how Confluence pages export

1. Install Scroll PDF exporter. When you need the Confluence export to represent your organisation in official documentation, investing in a Scroll Exporter is worth it. My preference is to PDF exports. If you rather export Confluence pages to MS Word documents then Scroll Word exporter provides a similar level of control.
2. If on Cloud, install “Scroll Exporter Extensions for Cloud”. With this app you can make local adjustments to control how the page exports. For example- you can force a page break in a specific location on the page.(On Data Center this is part of the Scroll app itself)

Prepare a Scroll PDF Exporter template

1. Define a Scroll exporter template that matches the stylesheet of your company. The default templates provided by Scroll, the “Article,” or the “Documentation” are good starting points. Copy one of them and adjust- for example, add the company logo to the header.
2. The template has a table style called “Default Table”. It is tried and tested, so do not to change its main characteristics: font sizes, padding, or margins. Most Confluence tables are not very wide or very long, and will look great with the “Default Table” style.
3. In the Scroll template, Under the Styles/Tables area, create a new table style. The new style will be more condensed than the usual style. We’ll use this style only for our huge tables. Easiest is to copy the “Default Table” style and change some settings:
   1. Rename the new style to “Condensed Table”
   2. In the section “Body cells/Content”:
      1. 1. Overwrite style of: Paragraphs, Numbered Lists, Bulleted lists
         2. Font size= 7pt
         3. Line height= 1
         4. Margins= Top: 3, Bottom: 3
   3. In the section “Cells”:
      1. Padding=3

In the Scroll PDF exporter template, define a style for condensed tables

Dust the Confluence page with some Scroll magic:

1. Open the page in EDIT mode
2. Most documents are better read on a Portrait aspect, which is the default aspect for the template. Wide tables need landscape, so review the page and decide when is the best point to transition to Landscape. Often this is before a header that proceeds the table. Navigate to that place and add the macro “Scroll Landscape”. This impacts only the export from Confluence, and will have no impact on how the page looks in VIEW mode.
3. After the table, add the macro “Scroll Portrait” – this will shift the document back to the Portrait aspect.
4. Right before the huge table, add the macro “Scroll Table Layout.” This macro impacts only the table that is right after it, so make sure it is right before the table. Add this to the macro configuration:
   1. Under the tab “Exporter specific” / “PDF & WORD exporter only” / Table styling: add the name of the Condensed Table style (that you defined in the template).
   2. Under the tab “General” / “Column width” provide directions on how to spread the columns along the width. This is where a lot of the magic happens. So how to find the optimal spread? As each table is unique, trial and error is the only way to find the right spread. Find below some tips on how to spread the columns, if your table is a specification table with Jira data.

In the Scroll Table Layout macro, instruct to use the condensed table style

What’s the optimal spread for column width

1. In the macro “Table Layout”,setting the “Column width” requires consideration of your actual table. The optimum is unique for each table.
2. As my experience relates to Jira Snapshots tables who are showing Jira data, these are some thumb-rules that work well:
   1. Short fields like “Issue key”, “Issue type” look fine when set to 8%
   2. “Summary” needs a bit more, like 10%
   3. A long text field will need 15% or more to look best.
   4. When optimising, this is the thought process:
      1. Some columns, like the issue-key, look bad when they are split to few lines- so try to give them enough sace not to wrap.
      2. Columns with a lot of text require the maximum width you can possible give them. The wider you can go, the shorter your whole document will be.

And… that’s it

Once you optimize your table layout macro your age is good to go.
And you now have a pattern you can use each time that you have a huge table. Using this method the number of pages used by your table will shrink by a factor of two or more. Moreover, the table will be pleasing to the eye.
Do you have big tables you need to export? If yes, go ahead and give this a try.

Here are images of before… and after improving how the Confluence table exports

A wide table exported, without optimisation

A wide table exported, with optimisation