Introducing the Atlassian Integration Guide.
- Do you have Jira and Confluence, and you want to make them play together?
- Did you know that Jira, Confluence, Fisheye and Crucible can get intimate with each other, and Subversion can join the party too?
- Do you ask yourself, what else do the Atlassian applications get up to when they’re all together?
You just may find the answers in the Atlassian Integration Guide.
At the moment, this documentation is a work in progress. But watch this space.
The Atlassian Integration Guide will:
- Provide the first port of call for technical and user information on integrating Atlassian applications.
- Show you how many integration points there are i.e. how you can make the Atlassian applications work together.
- Either contain or link to all information you need to do this.
For the technical writers out there
Using a wiki for technical documentation is always interesting. We thought you might like some information about the spaces, pages and macros we have used.
First there’s the Integration Guide itself. It is a Confluence space, containing a number of “integration point” pages like this one for Application Links.
Then there are all the related documentation spaces, which allow version control and provide a greater depth of information for each integration point. One such is the Application Links documentation space.
Consistent layout?
A technical writer will say,
It would be good if the “integration point” pages have a similar layout and the spin-off spaces have more or less the same structure.
How do we achieve that?
- For the “integration point” pages, we have a page template called the Integration Point Template. Page templates are an existing Confluence feature. When you add a Confluence page, you can base it on a page template.
- We have created a “template” space, containing the basic pages and layout needed for our documentation space.
- The template space is just an ordinary Confluence space, not a special Confluence feature.
- When we need a new documentation space, we use the Copy Space plugin to create a new space based on the template.
- We use space permissions to hide the template space, so that it is visible to Atlassian staff only. It contains no meaningful information, so we don’t want it to clutter the wiki for other viewers.
Duplication of content?
Looking closer, you’ll see that some of the information is shown in more than one place. Using a wiki as our document repository, how do we do that without duplicating the text?
Confluence allows you to include content dynamically from one page into another page. You can include a whole page into another one, using the {include} macro. You can also define an ‘excerpt’ on a page, and then include that excerpted text into another page using the {excerpt-include} macro.
So we have defined a set of pages called an “inclusions library”. This is not a specific Confluence feature, it’s just a way to use existing features. The inclusions library contains some pages with content that can be included into other pages and even into other spaces.
Clear as mud? Let’s take a look at an example:
- The Application Links space has an inclusions library.
- One of the pages in the library gives a general description of the Application Links feature: _About Application Links.
- The content of that page is included into the Application Links home page.
- The same content is also included into another space: The summary page in the Integration Guide.
Some notes about the inclusions libraries:
- The pages are located at the root of the wiki space, not under the “Home” page. This means that they will not appear in the table of contents on the left and they will not be picked up by the search in the left-hand navigation bar either.
- The pages will be picked up by other searches, because they are just normal wiki pages.
- For all new pages, we have decided to start the page name with an underscore e.g. “_My Page Name”. This indicates that the page is slightly unusual, and will help prevent people from changing the page name or adding content that’s too specific to a particular use case.
Table of contents including short summaries
The home page of the Atlassian Integration Guide lists the integration points and gives a short summary of each one. This rings alarm bells in a technical writer’s brain — duplication, extra maintenance effort, and so on.
But no. We are using the {children} macro to list the integration point pages, and to display the excerpts from each page. It takes just this one line to display the list plus summaries:
{children:page=Integration Points|depth=1|style=h5|excerpt=true}
Hint:
If you want to see how we’ve done something, try viewing the Wiki Markup on the page you’re interested in. Go to the ‘Tools’ menu and click ‘View Wiki Markup’.
We think the Atlassian Integration Guide is pretty cool
It will be even more awesomely useful as it expands over the coming weeks. And here’s the requisite gratuitous iPhone screenshot 😉
