Blog Archives

Linking to external blog posts from our documentation

At work, we’ve just started a new set of documentation pages called “Tips of the Trade“. The project is still in the early stages. I thought other tech writers might be interested, so I’m blogging about it now. There will be a page for each of the products we document. The pages contain a set of links to useful blog posts written by people out there on the www. It’s a way of giving our readers more information and a way of involving external bloggers, developers and authors in our documentation.

Here are the first two:

The pages for JIRA bug tracker and Bamboo build manager are under review. We’ll be adding pages for our other products soon too.

Why have we started doing this?

The idea has been skulking around my head for a while, and it finally got dragged out into the open two weeks ago when, for the umpteenth time, someone asked me how we use wiki spaces to manage documentation versions. My answer was to point them to a blog post I’d written on this topic. But first I had to sift through the plethora of blog posts to find the ones about doing tech docs on wikis. And it’s not only me. Our technical sales and support guys have repeated the same search many times.

How much handier it would be if we could point the enquirer to a whole set of links about using wikis for technical documentation. Or even better, how awesome if people could just find the links for themselves in our documentation. Time saved, for them and for us. FTW.

Funnily enough, apart from tech docs on wikis, there are other things in life too. For example, haven’t you been dying to know how to secure a Grails application with Acegi and Crowd, or how to do SSO for RoundCube Webmail? Heh, the Crowd “Tips of the Trade” page has links to people who’ve done it.

Bringing the idea to life

So I put together two strawman pages, one for Confluence and one for Crowd. That was a fun and interesting exercise in itself. It took many hours. I had to search for the blog posts, then read each one and decide whether it suited the purpose. Because we’re talking about the technical documentation, I was looking specifically for “how to” guides rather than the broader use case materials.

Then I blogged about the idea and the strawmen on our extranet (a Confluence site that we use for company blog posts, planning, information management and so on). The response was immediate and enthusiastic.

That’s one of the things I love about working at Atlassian — all the feedback and support you get when you post an idea on the extranet. If you get no comments, then there’s a good chance the idea is a dud.

A rose by any other name

Isn’t it so often true that finding the name is the most difficult part of a new project? The page title started out as “Tips from the Trade”. But that wasn’t quite right. So for a short period of time we dubbed the pages “Tips from the Coalface”. Not ideal either. So now they’re “Tips of the Trade”. Better, but still not awesome.

The title doesn’t really resonate, scintillate, titillate 🙂

Any ideas?

The page layout

To categorise or not to categorise? I decided to go for “soft categorisation”. I don’t know if that term has ever been used before, but it kind of expresses what I mean.

Our human brains like to categorise things. It gives us a fuzzy sense of security and well being 🙂 On a more mundane level, categories give a page a structure that is pleasing to the eye. They soften the “wall of text” effect. On the other hand, categories are fairly arbitrary or subjective and can hide valuable information.

So I put the blog posts into more-or-less meaningful categories, and put a box around each block of links with the category as title. But I didn’t mark the category as a heading. The result is that the table of contents at the top of the page does not show the categories. So you get the best of both worlds — a categorised and an uncategorised view of the world, uh, page.

For those who want to know the wiki markup:

  • The table of contents at the top of the page is produced by a {toc} macro, showing only heading level 6: {toc:minLevel=6|maxLevel=6}
  • The boxes are produced by the {panel} macro, with a choice of colours: {panel:title=Application Connectors
    |borderStyle=solid|borderColor=#ccc|titleBGColor=#6699cc
    |bgColor=#cee7ff}

Hint: You can see the wiki markup for yourself. Go to the Crowd Tips of the Trade, open the “Tools” menu and select “View Wiki Markup”.

I also decided not to put the posts into any particular order. I’m assuming that most people will find what they want via a search, so I’ve added some short descriptions of the content of each blog post.

Tips of an entirely different sort

Diversion alert!

This morning I had to trim the tips of my hair. Fully two inches off! But the cause of this tip-trimming is suitably romantic. My hair got hopelessly tangled when I flew in an open-cockpit Tiger Moth. Tip: If you ever get the chance to do something similar, tuck your hair under the helmet. It was a fantastic experience. Here are some pics and videos: Flying in a Tiger Moth.

A couple of months ago I radically pruned one of our bushes, because it was getting tall and a bit sparse in the middle. We were worried for a while that I’d been too enthusiastic. But now such pretty flowers have bloomed on all the blunt tips:

Linking to external blog posts from our documentation

Linking to external blog posts from our documentation

My faith in gardening “how to” manuals is restored 😉 A close up view:

Linking to external blog posts from our documentation

Linking to external blog posts from our documentation

What’s next for the “Tips of the Trade” project

When we have published more of the “Tips of the Trade” pages, I’ll write about them on the Atlassian blog. That way, our customers, community developers and community authors will know about them too. People will start stumbling across the pages via Google search and other searches, word of mouth, etc.

The documentation is on a wiki, so other Atlassians and contributors can add links to useful blog posts they come across. The tech writers monitor the wiki pages and will intervene if the links don’t quite suit the purpose of the document.

The pages provide useful information for our readers, especially about the edge cases and specific use cases that it’s so hard to cover in the core technical documentation. Thinking of the blog authors, they’ll probably like the fact that we’re linking to their posts. You scratch my back, I’ll scratch yours. That’s social, mate ÂŽ 😉

I’m totally enjoying the work of compiling the pages and it will be interesting to see what feedback we get.

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 🙂

Finding use cases for Crowd nested groups documentation

For a technical writer, it can be difficult to find those use cases and examples that bring the documentation home to the reader. This is especially so in an agile environment, where requirement- and functional specifications tend to the minimalist. When you’re explaining an intangible and complex concept like “nested groups in Crowd”, it’s good to have some concrete examples that your reader can identify with.

This week, we released Crowd 1.4. Crowd is a web-based single sign-on (SSO) and identity management tool. That’s complex enough. Now add one of a new features in this release, the esoteric “nested group”.

“Nested group” — Is that a cluck of broody chooks?*

I’m quite proud of the new documentation on nested groups. It has some good use cases and diagrams.

* A “chook” is what we call a chicken in Australia 🙂

Where did the use cases come from?

Given that I’m working in an agile environment, where documentation is not abundant, and also that I don’t have face-to-face contact with our customers, it might have been difficult to find meaningful use cases. So where did they come from? Our customers “talk” to us via our Confluence wiki and our JIRA bug tracker, as well as other channels like user forums, support requests, etc. For a technical writer, the community wiki and bug tracker can be a good source of information about requirements and the stuff that happens to our customers out there in the wild.

For the nested groups documentation, I gleaned a lot of information from people’s comments on the feature request in JIRA. Thank you to those people who made such informed and informative comments! All I had to do was transform the information into more generic examples and add some illustrations.

Diagrams on a wiki?

I used Gliffy to create the diagrams. When I first tried Gliffy, I was amazed and delighted. I still am. Gliffy is a third-party plugin for Confluence, created by Gliffy Inc. My hat off to you guys.

What’s so magical about Gliffy and these diagrams? It’s that you can create and edit the diagram on the wiki page. When you view the diagram, it renders as a JPG on the web page. But if you have wiki permissions to edit the page, you can edit the diagram too. The Gliffy drawing interface is very intuitive to anyone who has used other drawing packages. This means that the drawings are “part” of the wiki — anyone can update them (permissions permitting) at any time, from any place.

Where do other technical writers get their examples?

I’d be really interested to hear where you glean your information from, especially if you’re in an agile environment or writing the documentation from scratch, with very little information falling down the traditional SDLC waterfall to land neatly in your pool of words.

We’re not business analysts, so we don’t have the time to do a full use case analysis or requirements investigation. But we often do need concrete and real examples. Has anyone else mined a bug tracker, walked a wiki or surfed a user forum to find this sort of information, and do you have any other handy tips?

An illustrated use case for this blog post? 😉

A termite nest on a tree in Manly Dam Park (near Manly, NSW, Australia):

Finding use cases for Crowd nested groups documentation

Keeping up with the younger Crowd

One of the best things about technical writing is the variety it offers: who you work with; the style of writing required; the type of products you document; your input into and impact upon the products themselves; the medium you use, and so on. One of the products I work on is highly technical, and the documentation is funky that way too. The product is Crowd. If you find authentication, authorisation, single sign-on and user management sexy, then Crowd is for you. And the documentation would be your choice of bed-time reading.

This week we released Crowd 1.2, a major release with lots of new features. So we published many new and revised documents too.

Documenting this type of product is interesting. On the one hand, you get a kind of glow from belonging to the elite group of people who understand words like ‘Acegi’ and ‘OpenId’. You have the chance to indulge your natural inclination for long words and other esoterica. You may notice one or two creeping into this blog post 😉 On the other hand, in the documents themselves the trick is to know when to explain something and when not. After all, we have a savvy readership. I try to keep explanations short. Often all you need is a link to an authoritative website and an expansion of an acronym on first use.

Gourmet’s guide to a technical document: Mix the dry ingredients. Sprinkle in the acronyms. Pour the open source over the top.

Another interesting thing about this type of documentation is that the developers write much of the content themselves. As technical writer, I guide and tweak the content. When I can, I’m keen to jump in and test-drive the integrations myself before documenting them. But sometimes that’s not practical or efficient.

Wikis are great for collaborating like this. I might kick off a document by creating the skeleton structure. Then the developer writes the first draft. I jump in and tweak some things. The development lead and another technical writer do an in-depth review. And there you have it, a document to suit the epicurean taste.
Sometimes, you can even make the document look pretty:

Keeping up with the younger Crowd

Ain’t that just copacetic?

Have you noticed that your brain starts shooting off at a tangent when you’re writing dry technical kind of stuff? I had to explain ‘Acegi’ in the Crowd release notes:

Crowd 1.2 provides a built-in application connector for Acegi, a security solution with a particular emphasis on Spring Java/JEE applications.

Here’s what my gray matter kept insisting was relevant:

Spring has sprung, da grass is riz

I wonder where da boidies iz

Da boidies is on da wing

Don’t be absoid

Da wings is on da boid

That’s a jingle that my dad recited to me when I was just a kid. It’s spoken with a cockney or Bronx accent. Evidently the verse’s origins are obscure, though it’s often quoted, and sometimes cited as an anonymous work called ‘The Budding Bronx’. Isn’t it weird how such things stick in your head? A blog is a great place to get rid of such insistent promptings from the subconscious. The jingle would probably, though not indubitably, be considered out of place in the Crowd docs.

%d bloggers like this: