Cross-application plugins and their documentation

Over the last few weeks, I’ve been working on the guides for developers who write plugins (add-ons) for Confluence, Crowd and other Atlassian applications. This has been very interesting for a number of reasons: integration across different software applications, which translates to cross-application documentation too; content re-use while retaining the simplicity of individual guides for each application; developer documentation rather than user and administration guides; and last but not least, all the fun of an agile environment. And a wiki.

What’s a plugin?

A plugin is an add-on to an application, much like the bits and pieces you can add to your browser. People can write plugins to extend the functionality of Confluence, JIRA, etc. For example, you might write a plugin that adds a “Hallo” option to the Confluence “Tools” menu and displays “Hallo world” when clicked. Once you have written your plugin, you can make it available to other people too, by putting it into a common repository. There are a number of great plugins which provide some very cool functionality to Atlassian’s various applications.

What’s integration?

Atlassian is moving towards wider and more intimate integration between the different applications we develop. You can already do things like display a dynamic list of JIRA issues on a Confluence page, or display FishEye repository information on a JIRA page. Now the plan is to make the applications work even more closely together.

Developing a common plugin framework is one of the big parts of the move towards even deeper integration, because the plugin framework will help developers (both Atlassians and others) to write plugins that work on more than one of the products, and it will also allow plugins on each product to have a consistent look and behaviour from a user’s point of view, even when the plugin works on only one application.

How does this affect the documentation?

As is so often the case, the architecture of the applications affects the architecture of the supporting documentation. We needed a documentation system to cater for developers who want to write cross-application plugins. So they need to know the full details of the common plugin framework. But we also needed to cater for people wanting to write a simple plugin for just one of the applications. Those people don’t necessarily need or want to know that there’s a singing and dancing plugin framework behind the scenes. They just want to know how get their plugin up and running as easily as possible.

We also needed to ensure that common information is held in one place only, even though it may be used in multiple places. This is an excellent example where content re-use is essential and neatly matches the product architecture.

Why is it fun and agile?

Writing developer documentation is an essentially cerebral experience ๐Ÿ™‚ The main reason is that we technical writers don’t really have the time to actually test out this sort of documentation. When writing a user guide, administration guide or installation guide, we actually do the stuff and then write how it’s done. But with developer documentation, we rely more on input from the developers and architects, and then we organise the information into a cohesive documentation set. So I had the opportunity to draw some pretty pictures and to work on a purely intellectual basis, organising information without any UI in between.

The agile development aspect of it is also fun. We’re developing the plugin framework in phases, and slotting it into the various applications as and when they’re ready to receive it. So our design must allow the documentation for one application to grab content from a specific version of the plugin framework documentation. More than that, different versions of the same application will grab content from different versions of the plugin framework documentation. There are people out there using various historical versions of the applications at any one point in time, and they need the correct version of the documentation too.

And all of this on a wiki ๐Ÿ˜‰

What’s the plan and where are the pretty pictures?

By the way, I drew these diagrams on Confluence, using the Gliffy plugin. Then I exported them as jpeg images, later converted to png, so that I could include them on this blog post. Gliffy is one example of a great Confluence plugin, created and sold by a company other than Atlassian.

Here’s the design for the first release of application documentation which incorporates the common plugin framework documentation. Each box in the diagram below represents a documentation space on our Confluence wiki.

Cross-application plugins and their documentation

Cross-application plugins and their documentation

We use spaces as the version-control mechanism for the documentation.

The content in the plugin framework spaces is designed to be re-usable. The re-usable chunks are contained in a page hierarchy called an “inclusions library” and given a page name starting with an underscore, so that people see instantly that they’re special.

The application-specific documentation will dynamically include content from the plugin framework spaces using the {include} macro. In some cases, we may just link to the plugin framework documentation instead.

So here’s the way things may look some time early in 2009. This is just the documentation design, not a forecast of the actual application versions involved. It shows how we’ll have multiple documentation spaces in Confluence, for the plugin framework and for the applications. The arrowed lines show how each application version will pull in content (via Confluence {include} macros) from a specific version of the plugin framework documentation spaces.

Cross-application plugins and their documentation

Cross-application plugins and their documentation

Want to see it working?

It’s all happening.

We have the Plugin Framework 2.0 documentation in one space, and the about-to-become Plugin Framework 2.1 documentation in another space. (It’s undergoing metamorphosis at this very moment, awaiting the release of the next version of the framework.)

Crowd 1.5 supports version 2.0 of the Atlassian Plugin Framework. The Crowd plugin documentation now grabs and displays the correct version of the plugin module types. If you’re interested, you can take a look at these pages, to see the {include} macros in action. You can view the Wiki Markup code by clicking “Tools” –> “View Wiki Markup”:

What about hiccoughs?

Hiccoughs? On a wiki? Never! ๐Ÿ˜‰ But I did find a few things to be aware of:

  • If you want to dynamically include content across spaces, you must use the {include} macro โ€” the {excerpt-include} macro does not work across different spaces.
  • The above fact means that all pages your inclusions library must take into account that the entire content is dumped into the middle of another page. So the pages should not contain “related topics” or {toc} or other context-related data.
  • We need to hard-code the space key into the {include} macros. For example, all the {include}s in the Crowd pages start with {include:PLUGINFRAMEWORK20:_Page Name}. So when Crowd moves to the next version of the plugin framework, we’ll need to manually change all these references to something like PLUGINFRAMEWORK21. This is a known limitation of Confluence macros.
  • The search does not pick up the content when ‘included’. To solve this, we’ll need to add labels to the pages to ensure the most relevant data is picked up by search.
  • There was a slight caching oddity when I used the Copy Space plugin (another great plugin, by the way) to create the version archive for PLUGINFRAMEWORK20. I had to manually refresh the pages to ensure that the ‘included’ content showed up properly in the Crowd docs. I’ll keep an eye on this.

Next up is Confluence 2.10, still under development. Other applications will follow. So there’s lots more fun in store for the Atlassian tech writers ๐Ÿ™‚


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 25 October 2008, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , , , , . Bookmark the permalink. 5 Comments.

  1. Very interesting stuff. It sounds like the challenge you’re facing is one of single-sourcing, where the documentation content has to compose in the same ways as the code libraries.

    What I’m especially interested in, though, is: what happens to the documentation *of* the plug-ins? If I am a plug-in creator, and I write documentation for my plug-in, how does that get integrated with the documentation of the application?

    In Eclipse, which is another application framework I’m somewhat familiar with, the TOC of the plug-in’s help simply gets appended to the TOC of the application’s help. (I think DotNet works similarly, but I haven’t looked into it.) Unfortunately, this tends to lead to a feature-centered organization for the help, rather than a task-centered one.

  2. Hallo Janet

    “What happens to the documentation *of* the plug-ins?”. That’s a very good question ๐Ÿ™‚ At the moment, Confluence has a fairly good mechanism allowing developers to create HTML fragments, which are then included on a page which the user accesses by clicking a help link from Confluence itself. The page is called the Notation Guide. (Yes, that could be improved upon ๐Ÿ™‚ ) The link appears when you’re editing in Wiki Markup mode. This is documented here.

    This means that the user will see the guides for the plugins/macros installed on their specific Confluence instance, which is pretty cool.

    The other Atlassian applications don’t have this functionality yet. It’s one of the many things we’d like to improve on the user assistance side of things.

    I had a look at your blog — great stuff. I’ll be wandering over to take a look more often ๐Ÿ™‚

    Seeya, Sarah

  3. Thanks for the great real life example of the Gliffy Plugin. If you create your diagram in Gliffy Online you can post the link to your blog — then it will automatically update without you needing to repost it. Best to you,
    debik at gliffy dot com

  1. Pingback: Links Roundup: Technical Writing | Shanghai Tech Writer

  2. Pingback: Free of All ยป Blog Archive » Links Roundup: Technical Writing

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: