Blog Archives

Content reuse on a wiki – a case study

Recently I finished developing the documentation for a new user directory management framework that’s incorporated into two of our products. When designing the documentation, one of the primary goals was efficient and effective content reuse. Since we do all our documentation on a wiki, this was an interesting and rewarding exercise. So I thought you may like to read about it. 🙂

The reusable chunks of documentation are in the User Management (USERMAN) space on our documentation wiki. The chunks are used in the Confluence administration guide and the JIRA administration guide.

What the documentation is about

The documentation describes a software framework for managing user directories. A user directory is a place where you store information about users and groups. Using the software, administrators can connect various types of user directory to their application, and manage the directory connections. A directory can be an internal directory, with data stored on the product database, or an external LDAP directory like Active Directory, or even another application that manages the user information and directory connections.

Why content reuse makes sense for this documentation

The user directory management framework itself consists of a set of back-end libraries and a user interface plugin. The libraries and UI plugin are currently used in two separate products, Confluence and JIRA. The business rules followed by the back-end process and the UI experience are therefore the same in both Confluence and JIRA. In future, other products may join the party.

It makes sense to share the documentation too. This will ensure a consistent experience for our customers across the products, and improve our efficiency when maintaining the documentation.

Introducing the USERMAN space

The User Management (USERMAN) space contains the reusable chunks of documentation. Its home page looks a little different from our standard documentation home pages. A standard home page introduces readers to the documentation and gives them links to the user’s guide, administrator’s guide, and so on.

Instead, the USERMAN home page:

  • Lets readers know that “This documentation is not intended to be read independently of the JIRA and Confluence documentation” and gives them links to those documentation spaces. This is necessary because many people come to our documentation via Google searches. If they land on this home page, we want them to find their way to the relevant documentation quickly.
  • Tells authors where they can find the reusable chunks within the space.
Content reuse on a wiki - a case study

Home page of the USERMAN space

A simple example of content reuse

Let’s start with a simple topic, configuring the LDAP connection pool. The reusable chunk is in the USERMAN space: _LDAP Connection Pool Settings. Here’s a screenshot of the content of that page:

Content reuse on a wiki - a case study

A chunk of reusable content

The above page consists entirely of reference information. There is no orientation at the top, nor any other context apart from the standard message telling readers where to go for the “real” documentation.

The content of the page is reused in both the JIRA documentation (Configuring the LDAP Connection Pool) and the Confluence documentation (Configuring the LDAP Connection Pool). Here’s what it looks like on the JIRA page:

Content reuse on a wiki - a case study

LDAP connection pool in the JIRA documentation

On the JIRA page shown above, there’s:

  • Contextual information at the top of the page.
  • JIRA-specific “how to” instructions.
  • Reused content: The chunk of reference information, dynamically copied in from the USERMAN space when the page loads into the browser.
  • More contextual information, in the form of “related topics”, at the bottom of the page. (Not shown on the screenshot.)

How do you include content from one page into another?

Confluence wiki provides the {include} macro. To use the macro, you edit your page and enter the macro name in curly brackets, specifying the space key and the page title of the page that you want to include into your page.

For example, the above JIRA page contains this macro code:

{include:USERMAN:_LDAP Connection Pool Settings}

When Confluence renders the page, it will replace the macro code with the content of the “_LDAP Connection Pool Settings” page from the “USERMAN” space.

If you like, you can find out more in the documentation for the {include} macro.

The design of the reusable content

Here’s a summary of various design considerations and decisions:

  • Reusable content in a separate space. I decided to house the reusable chunks in their own space, rather than in one of the product documentation spaces. This is because the information is independent of any specific product.
  • Reusable chunks hidden from the reader. Well, as much as possible. The topics in the USERMAN space are not visible in left-hand navigation bar, but people will find them if they search for them. We need to make it clear to readers that the USERMAN space is not intended for reading independently of the product documentation. We also give readers links pointing to the relevant JIRA and Confluence documentation.
  • Inclusions library. Put the topics in an “inclusions library” and start each page name with an underscore. This will alert both readers and authors to the fact that there’s something different about the page, and will help prevent people from changing the page name (which breaks the auto-inclusion). A while ago, I wrote a post about inclusions libraries. One thing to note is that an “inclusions library” is not a feature of the wiki. It’s just a convention we have adopted. The page called “_InclusionsLibrary” is just a page with a funny name. 🙂
  • Spaces as a mechanism for version control. When we release a significant new version of the user management framework (either the back-end libraries or the front-end user interface) we will need to publish a new version of the documentation too. Then, as each product incorporates the new version of the user management framework, we will adjust the product documentation to include the relevant version of the user management documentation. To make this work, we will create a new USERMANxxx space for each version of the documentation. The “xxx” represents the version number.
  • Size of the reusable chunks. How do we decide how big the reusable chunks should be? Well, this is a biggie, so I decided to devote a whole section to it. See the next section, after the screenshot.

Looking at a tree view of the pages in the USERMAN space, you’ll notice that the space home page (marked with the house icon, and at bottom of the screenshot) has no child pages. In a “normal” documentation space, you’d expect most of the pages to be children of the home page. Instead, in USERMAN all the pages are children of the “_InclusionsLibrary” page.

Content reuse on a wiki - a case study

Tree view showing the pages in the USERMAN space

Deciding the size of the reusable chunks

On the one hand, the smaller the chunks the better. Small pieces of content give us much more flexibility. We can use them in different sequential orders and in different contexts. We can add product-specific and contextual information between the chunks. We can leave out bits in one product and include them in another. We are less affected by changes in the user interface, for example when the order of the input fields changes or entire sections move to different screens.

On the other hand, smaller chunks are more difficult to manage. Every time we need to update the page inclusions, such as when we need to move to a new version, there are a large number of {include} macros to update. This reduces the benefit of efficient maintenance. Too much flexibility may lead to confusion in the final output that the reader sees, reducing the benefit of cross-product consistency.

You could go to one extreme and have a reusable chunk per input field or concept (“setting the optimal size for your LDAP connection pool”). Or you could go to the other extreme and define one large reusable chunk per user task (“connecting an LDAP directory”).

After discussion with the product manager and development team, I decided to go for a middle-of-the-road approach.

  • Most of the reusable content is reference material and conceptual material, rather than “how to” steps.
  • We divided the content into logical blocks, corresponding to a logically-related set of input fields or to a concept.

The result is:

  • For the simpler task-based topics, there are two page inclusions: one for the concept and one for the reference material. Example. (To see the wiki markup source of a page, click “Tools” and select “View Wiki Markup” from the dropdown menu.)
  • For the more complex topics, the number of inclusions ranges from five to ten: one or two conceptual chunks,  a number of reference chunks and one or two illustrative chunks. Example 1. Example 2.

What about the procedures and context that are specific to the product?

In the documentation pages for Confluence and JIRA, there are sections that are specific to the product and sections that are common to both products.

These bits are specific to the product, and therefore not reusable:

  • Procedures: The primary user interface is different for each product, and so the path that the user takes (click here, select this, click that) to get to the directory connection screens is specific to the product. Once the user has reached the directory connection screens, the user interface is the same for both products.
  • Context: It’s a good idea to start each page with a mention of the product (Confluence or JIRA) and other orienting information, so that the reader knows what the page is about. After that, it’s safe to dive into the reused content which, of course, is free of contextual information.
  • More context: The path within the documentation itself differs. For example, we need to give people links to related topics and parent pages.

Each documentation page therefore has a section or sections of reused content, with a wrapping of product-specific content.

Diving into a more complex example of content reuse

Let’s take a look at a complex topic, connecting to an LDAP directory.

The topic has a number of sections:

  • A short introduction to the page.
  • An overview of the LDAP connections provided and why you’d use them.
  • A “how to” procedure.
  • Seven sections containing details of specific settings.
  • Diagrams of possible configurations.
  • Related topics

Only three of the above sections contain content specific to the product:

  • The short introduction.
  • The “how to” procedure.
  • The related topics.

All the other sections are drawn from reusable chunks:

  • An overview of the LDAP connections provided and why you’d use them.
  • Seven sections containing details of specific settings.
  • Diagrams of possible configurations.

To see this at work, go to the page (for example, in the Confluence documentation, Connecting to an LDAP Directory), hover over the “Tools” button and select “View Wiki Markup” from the dropdown menu. You’ll see that most of the page consists of headings and {include} macros like this:

h2. Server Settings
{include:USERMAN:_LDAP Server Settings}
h2. Schema Settings
{include:USERMAN:_LDAP Schema Settings}
h2. Permission Settings
{include:USERMAN:_LDAP Permission Settings}

The first {include} macro draws in a reusable chunk from this page in the USERMAN space: _LDAP Server Settings.

The corresponding page in the JIRA documentation (Connecting to an LDAP Directory) looks very similar to the Confluence page.

Reusing Gliffy diagrams

This is something pretty cool that I discovered when creating this set of documentation. You can use the {include} macro to pull in a page that contains a Gliffy diagram. Let’s say you have a Gliffy macro on Page A. Then on Page B, you insert an {include} macro that pulls in Page A. Confluence will faithfully reproduce the diagram on Page B, as well as Page A.

That’s awesome!

Here’s an example. This page in the USERMAN space contains just a Gliffy diagram and its caption: _Diagram Confluence JIRA Crowd.

Here’s a screenshot of the above page:

Content reuse on a wiki - a case study

A reusable Gliffy diagram

Reusing the diagram:

Developing the design

The exercise of designing the reusable content was interesting in a couple of aspects.

  • First, the end result would be a set of reusable chunks, only loosely resembling the “documentation” that most subject matter experts are used to seeing. How could I prototype the design and the content with them?
  • Secondly, the content would be used in two different sets of documentation, for two different products: Confluence and JIRA. Only the Confluence documentation is “mine”, in terms of technical writing responsibilities. Two other technical writers manage the JIRA documentation. I needed to make sure they had input into the design and were happy with the end result.

The usual process of consulting and collaborating with subject matter experts when designing a new documentation suite goes something like this: Draft the table of contents, review it with product managers and developers, apply changes, add detail, and refine it until we’re all happy.

The difference was that there were two tables of contents:

  • The list of topics and their hierarchical structure as they would appear to readers. Let’s call this the compiled documentation
  • The list of reusable chunks that we would plug together to form the above readable material. Let’s call these the reusable chunks.

My strategy was to discuss and review the planned table of contents for the compiled documentation in great detail, making sure that I covered all topics and was consistent in the amount of attention given to each subject. Then I designed the reusable chunks to best satisfy the requirements so discovered. When designing the reusable chunks, I relied more on my technical writing and information design skills.

As soon as we had a basic design, I created the draft content in the reusable chunks and hooked them together to create the compiled documentation for one of the products.

Then I walked the technical writing team, product managers and developers through that first draft. I showed them the reusable chunks and discussed the design strategy (size of the chunks, use of wiki spaces, setting of permissions, consistency, removal of context, and so on). But most of our attention focused on the human-readable documentation. The review session, as always, gave me much valuable feedback that I applied to the draft.

After that initial review, I focused on each individual topic and went through the usual iterative procedure of drafting, reviewing and updating the content.

The tools

A summary of the tools I’m using for this case study:

  • Confluence wiki.
  • The {include} macro, supplied as part of Confluence.
  • Spaces, the primary way of organising content into logical collections, or libraries, in Confluence.
  • The Documentation theme, supplied as part of Confluence. In fact, you do not need the Documentation theme for content reuse. All of the techniques mentioned in this post will work in the default Confluence theme and most other themes too. But I’ve mentioned the Documentation theme here because the screenshots show it in action, in particular the left-hand table of contents supplied by the theme.
  • Gliffy online diagramming tool. Again, this tool is not needed for content reuse. I’m including it in the list because it’s an interesting part of the case study.

That’s it for now

I hope you find the examples and design tips useful!

How to copy a Gliffy diagram

The Gliffy blog gives a great description of how to copy elements from one Gliffy diagram to another. Here’s a slightly different technique, for copying an entire Gliffy diagram from one Confluence page to another. You could also use this technique to copy a diagram from one Confluence site to another.

I demonstrated this technique to a colleague recently, and I’ve decided to blog about it in case anyone else finds it useful. In summary:

  • Go to the Confluence page that contains the Gliffy diagram and download the attached file that has the scary comment “GLIFFY DIAGRAM, ONLY EDIT IN GLIFFY EDITOR!” This is the Gliffy data file.
  • Remove any extension that your browser may add to the file name.
  • Upload the Gliffy data file as an attachment to the page where you want a copy of the diagram.
  • Insert the Gliffy macro onto the Confluence page. For the diagram name, give it the name of the attached Gliffy data file.
  • If the diagram shows up as empty, open and close the Gliffy editor to jog the diagram into life.

Step 1. Download the Gliffy diagram’s data file

Gliffy stores all the information about a diagram in a file attached to the Confluence page. The attachment’s name is the name of your diagram. The comment next to the attachment lets you know in no uncertain terms that you shouldn’t mess with this data file. 😉

Here’s a Gliffy diagram displayed on a Confluence page (click the image to see a larger version):

How to copy a Gliffy diagram

This screenshot shows the Gliffy data file attached to the Confluence page:

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

Download the Gliffy data file onto your computer:

  1. Go to the Confluence page that contains the diagram, and select “Tools” then “Attachments” to get to the “Attached Files” page as shown above.
  2. Find the Gliffy data file in the list of attached files. The file name will be the name of your diagram. (In my case, it’s “Atlassian Plugin Development Platform”, which is a bit unfortunate because that’s also the page name. Please excuse any confusion that may cause!) The “Comment” column contains the words “GLIFFY DIAGRAM, ONLY EDIT IN GLIFFY EDITOR!” next to the relevant attachment.
  3. Right-click the file name and select “Save link as…” (or whatever words your browser uses to offer you the ability to download a file and save it on your computer).
  4. Save the file on your computer.
  5. Check the file name on your computer carefully. It should be just the diagram name, without an extension. In my case, it’s just “Atlassian Plugin Development Platform”.
    Note: Some browsers (IE, I’m looking at you) add an extension, often “.xml” or “.htm”. If that’s happened, remove the extension.
  6. If you like, you can change the file name itself, if you want your new diagram to have a different name. I’ve decided to change mine to “CopyTest”.

Step 2. Upload the Gliffy data file to another page

Now you can just upload the Gliffy data file, in the same way as you would upload an image, a screenshot or any other attachment.

  1. Go to the Confluence page where you want to add the diagram, and select “Tools” then “Attachments” to see the “Attached Files” page.
  2. Drag and drop the Gliffy data file onto the “Attached Files” page, or click “Browse” and upload the file in the usual way.

Here’s my Gliffy data file, now called “CopyTest”, attached to a Confluence page. Notice that it does not yet have the Gliffy warning in the comment column. This is because neither Gliffy nor Confluence knows at this stage that the file is actually a Gliffy file.

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

FYI, the Gliffy data file contains a lot of text. In my case, the file starts with this text:

<stage keygen_seq="71"><pageObj drawingHeight="550" drawingWidth="700"

 

Step 3. Insert the Gliffy macro onto the Confluence page

Now you just need to let Gliffy and Confluence know there’s a diagram on the page. You do that by adding the Gliffy macro onto the page.

If you’re a wiki markup fan, just copy the markup from the original page and update the diagram name if you changed it. In my case, the original wiki markup looked like this:

{gliffy:name=Atlassian Plugin Development Platform|align=left|size=L}

I have changed the name of my diagram to “CopyTest”, so I inserted the following markup onto my page:

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

If you prefer to use the rich text editor and the macro browser, then just supply the file name and other parameters in the usual way.

Step 4. Edit the Gliffy diagram to cement the relationship

Often, the relationship between the Confluence page and the Gliffy diagram needs a jolt to get it started! After adding the macro, you may notice that your Gliffy diagram looks empty:

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

Just click “Edit Diagram” under the empty box to open the Gliffy editor. Then close the editor again.

Voilà!

 

How to copy a Gliffy diagram

How to copy a Gliffy diagram

 

My environment

I’m using Gliffy 2.0.2 on Confluence 3.3.3.

Hmm, that’s quite an old version of Gliffy. I see that the latest version is 3.0.6! I’ll lodge a request to get our plugin upgraded. 🙂

Older versions of Gliffy included the page name etc in the macro data

Older versions of Gliffy used to include more information in the macro data: the space name, page name and page ID. For example, your wiki markup may look like this:

{gliffy:name=Network topology|space=DOC|page=Recommended network topology|pageid=107610617|align=left|size=L}

Note: If your version of Gliffy does this, you will need to change the space name, page name and page ID to match the new page where you have put the copy of the diagram. This is very important. If you leave them at the old values, then the new page will actually display the diagram from the original page, not from its own attachment. This can lead to unexpected results, especially when someone edits the diagram from either page.

What about JIRA?

I wonder if you could use this technique to copy a diagram from JIRA to Confluence or vice versa? Let me know if you’ve tried it.

<stage keygen_seq=”71″><pageObj drawingHeight=”550″ drawingWidth=”700″ istt=”true” print_scale=”0″ print_grid=”0″ print_paper=”LETTER” print_layout=”0″ pb=”0″ stg=”1″ gr=”1″ fill=”16777215″ height=”550″ width=”700″><styles><shapeStyle lineColor=”global:0x333333″ fillColor=”global:26112″ gradientOn=”true” dropShadowOn=”false” lineWidth=”-1″/><lineStyle end=”0″ begin=”0″ width=”1″ pattern=”0″ color=”0x333333″/><textStyle color=”0″ style=”bold=true” size=”18″ face=”Arial”/></styles><objects><object order=”0″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”3963061″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”480″ y=”528″ x=”290.5″ libraryid=”com.gliffy.basic” shp_id=”2″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian Plugin Framework</B></FONT></P>]]></text><connlines/></object><object order=”1″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”3963061″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”528″ x=”621″ libraryid=”com.gliffy.basic” shp_id=”4″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Static plugins</B></FONT></P><P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>(v1)</B></FONT></P>]]></text><connlines/></object><object order=”2″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”3963061″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”480″ y=”428″ x=”290.5″ libraryid=”com.gliffy.basic” shp_id=”5″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>OSGi plugins</B></FONT></P><P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>(v2)</B></FONT></P>]]></text><connlines/></object><object order=”3″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”240″ x=”122.5″ libraryid=”com.gliffy.basic” shp_id=”6″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian REST Plugin Module</B></FONT></P>]]></text><connlines/></object><object order=”4″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”140″ x=”123″ libraryid=”com.gliffy.basic” shp_id=”7″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Shared Access Layer (SAL)</B></FONT></P>]]></text><connlines/></object><object order=”5″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”140″ x=”288″ libraryid=”com.gliffy.basic” shp_id=”8″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian User Interface (AUI)</B></FONT></P>]]></text><connlines/></object><object order=”6″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”103″ libraryid=”com.gliffy.basic” shp_id=”9″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Unified Plugin Manager (UPM) </B>to be included soon</FONT></P>]]></text><connlines/></object><object order=”7″ dshad=”false” gradon=”false” linew=”1″ linec=”0″ fill=”16777215″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”29″ width=”615″ y=”63″ x=”355″ libraryid=”” shp_id=”20″ class=”text_shape”><text><![CDATA[<P ALIGN=”LEFT”><FONT FACE=”Arial” SIZE=”18″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Components of the Atlassian Plugin Development Platform</B></FONT></P>]]></text><connlines/></object><object order=”8″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”16763904″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”80″ width=”145″ y=”240″ x=”288″ libraryid=”com.gliffy.basic” shp_id=”31″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian Template Renderer</B></FONT></P>]]></text><connlines/></object><object order=”9″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”230″ libraryid=”com.gliffy.basic” shp_id=”43″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Unified Application Links (UAL) </B>to be included soon</FONT></P>]]></text><connlines/></object><object order=”10″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”352″ libraryid=”com.gliffy.basic” shp_id=”44″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>OAuth </B>to be included soon</FONT></P>]]></text><connlines/></object><object order=”11″ dshad=”false” gradon=”true” linew=”2″ linec=”3355443″ fill=”26112″ text-horizontal-pos=”center” text-vertical-pos=”middle” lock=”false” fixed-aspect=”false” rot=”0″ height=”65″ width=”105″ y=”333″ x=”476″ libraryid=”com.gliffy.basic” shp_id=”45″ class=”round_rect”><text><![CDATA[<P ALIGN=”CENTER”><FONT FACE=”Arial” SIZE=”12″ COLOR=”#000000″ LETTERSPACING=”0″ KERNING=”0″><B>Atlassian Gadgets </B>to be included  soon</FONT></P>]]></text><connlines/></object></objects></pageObj></stage>

Technical writers hold an innovation sprint

At Atlassian, where I work, the pace is fast and furious. Always. It’s fun, invigorating, challenging, and I wouldn’t have it any other way. But there’s just never a breathing space. So when do we find the time to think about innovative techniques or procedures in our technical writing and documentation? The answer to that one is, all the time. If we have an idea, we’re encouraged to blog about it and see what people think. OK, cool, now we have some ideas. How do we find the time to put them into practice? That’s more difficult.

A couple of weeks ago we held an “innovation sprint”. This is a new idea, designed to tackle exactly the problem of finding that time to try out our innovative ideas. It worked and it was a lot of fun. Chocolate was of course inevitable. We wore some funny hats. And we made great progress on our innovation projects. So I thought I’d tell you about it.

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

What’s an innovation sprint?

Well, it’s a new idea. I haven’t heard of anyone else doing it, but if they do then their innovation sprints may have a different format. Here’s how we ran ours.

Planning: To prepare for the innovation sprint, we set a date and decided what each person would be doing during the sprint.

To take a step back, let me tell you about our “innovation register” and “innovation deputy” role. We already have an innovation register where we collect any ideas coming from us or from anyone else. The idea has to be something new. It can be procedural or part of the documentation itself. We also have a designated innovation deputy, a team member who is keen on innovation and who brings in new ideas, coordinates activities and makes sure everyone has an innovation project to tackle. The idea of an innovation deputy is also new, and I’ve filled the role for the last 6 months. The team lead and innovation deputy regularly discuss the new ideas with the rest of the team, and together we all decide which items are feasible and who would like to tackle what. So we made use of this register for our innovation sprint.

The sprint: We allocated a day for the innovation sprint itself. Yes, a whole day. Luxury! On that day, the technical writers planned to do nothing except work on an innovative idea for our documentation. Preferably, the project should be something that’s agreed upon beforehand with the rest of the team, and preferably it should be an item from the innovation register.

Demo: We also allocated an hour a couple of days later, where each of us demonstrated what we had managed to achieve during the sprint.

Hint: Schedule the demo session for a couple of days after the sprint. Even better, put a weekend between. That way, people have time to tidy up what they did and compile their demo. In our case, two of us were so fired up by the sprint, which happened on a Friday, that we worked over the weekend to finalise our project and have something to show. Cheating? Nah! Because it’s all about the ideas and the feeling good, not about the time.

Why the funny hats?

We wanted a tactful way of letting people know that the technical writers were otherwise engaged for a day. It worked. And it was funny. Here’s a typical conversation I had a few times with people coming into the office that day:

Newcomer: Is it tech writer hat day?
Me: No, we’re doing an innovation sprint today. The hats are a subtle way of saying, “Keep off, no doc requests today.”
Newcomer: Oh, that’s your thinking hat!

What did we get done?

A lot!

Giles continued working on his automated documentation publishing tool. This is a long-term project, fondly known as the “releaserator”, aiming to automate some of the procedures the technical writers follow when publishing documentation updates on release day.  We write and publish our documentation on Confluence wiki. There are some things the wiki does not yet do, from the point of view of publishing technical documentation. Giles is developing a plugin for Confluence to fill some of the gaps. The releaserator now has an awesome prototype of the configuration screen it will need in the Confluence space administration section. As a bonus, Giles is now a Velocity fundi. (We’re not sure that he ever wanted that distinction, but hey, who’s complaining.) Here’s the prototype of the configuration screen (click the image to see a larger version):

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

Rosie continued with her flowchart visualisation project. The aim is to use Gliffy to display a hyperlinked diagram at the top of each page in a procedural document. The diagram has a box for each stage in the procedure. The step you’re currently working on is highlighted and the boxes are hyperlinked so that you can move easily from one step to another. This project is not yet visible on any published pages. Here’s a screenshot of the prototype:

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

Andrew started work on a shiny new conceptual overview of Confluence wiki, also using Gliffy. Although still a work in progress, this page will soon become an awesome and useful document for our customers. It consists of a couple of diagrams showing the conceptual components of Confluence, such as the dashboard, spaces, pages, comments and labels. Each component is hyperlinked to the documentation page that describes that component.

I finalised my project called “Tips via Twitter”. The aim is to encourage people to tweet hints and tips about our products. What’s more, we publish a live Twitter stream on a page in the documentation. Tips via Twitter is now live for one of the Atlassian products, Confluence wiki. After one month’s trial, ending in mid-July, we will decide whether to roll out Twitter tips for another product called JIRA. I wrote about this project in an earlier blog post: Hints and Tips via Twitter.

What about the chocolate?

Ed, our team leader (not pictured above), went on a quest throughout Sydney to find some unique chocolates. Since the Atlassian technical writers are all such chocolate connoisseurs, it’s hard to find something new. But Ed came up trumps with these chocolates from Adriano Zumbo Chocolat Café in Balmain:

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

The flavours were, well, unique:

  • Strawberry and balsamic (front right, the smooth square one with silver dust on them). Pow! Taste sensation. At first powerfully sour. Then a bit overwhelming, but suddenly melting away to nothing at all. This was my favourite.
  • Chilli (front left, the dark, igloo-shaped one). Nothing special, actually.
  • Lemon (middle right, the corrugated one). Sour. Nice, but not as dramatic as the strawberry ones.
  • Dark chocolate honeycomb (middle left, the irregularly shaped one). Tasty. More or less as you’d expect, and nice and fresh.
  • Coconut, coriander and cardamom (at the back, the coconut cluster). Good. Again, more or less a conventional coconut cluster, but nice and fresh.

The innovation sprint was good. We plan to hold them regularly from now on.

Solving a problem with the Confluence Copy Space and Gliffy plugins

Last week I used the Copy Space plugin to create an archive of the Confluence 3.1 documentation, because we’ll be releasing Confluence 3.2 very soon. I ran into a problem when the space copying procedure encountered a fairly old Gliffy diagram. It’s possible that you may hit the same problem next time you use the Confluence Copy Space plugin. Here’s the workaround.

In short: Open the offending diagram in the Gliffy editor and then save it again. There’s no need to make any changes. Start the space copying procedure again. You’ll need to do this for each diagram that triggers the error.

A bit of background

We write and publish our technical documentation on Confluence wiki, and we use wiki spaces as the mechanism for version control. For each major release of the software that we’re documenting, we create a separate space containing the documentation specific to that version. We use the Copy Space plugin to copy the current documentation into a new space. I’ve written more about this procedure in an earlier blog post. (A by the way: Atlassian support does not cover the Copy Space plugin — but we use it.)

We also use another plugin called Gliffy to draw and display awesome diagrams. I’ve written about Gliffy in an earlier blog post too.

So last week I started the Copy Space plugin and hit a problem.

The symptoms

The space copying procedure runs for a while and then stops. The log files show an error message something like this:

…CopySpaceException: An error occurred while copying an attachment…. AttachmentDataStreamSizeMismatchException: Attachment data stream contains a different number of bytes to the declared size of the attachment.

If you have the very latest version of the Copy Space plugin, you will see a nice neat error message on the screen, including a link to the offending diagram:

Solving a problem with Confluence Copy Space and Gliffy plugins

Solving a problem with Confluence Copy Space and Gliffy plugins

Here’s the text of the above error message:

An error occurred while copying the space. The copy was cancelled.
The content that could not be copied was titled: <Gliffy image name>. link
The attachment’s size property does not match the attachement’s data size: Attachment: <Gliffy image name, version, attachment ID and author’s username>

Unfortunately, earlier versions of the Copy Space plugin don’t give such a useful error.

If you like, you can take a look at the bug report too.

The problem seems to happen for old diagrams only. (I encountered 3 such diagrams when copying the Confluence documentation this week.)

The solution

The workaround is simple: Open the offending diagram in the Gliffy editor and then save it again. There’s no need to make any changes to the diagram. If you have the latest version of the Copy Space plugin (version 1.2) the error even includes a link to the offending Gliffy diagram.

Start the space copying procedure again.

You’ll need to do this for each diagram that triggers the error.

Software versions

I’m using these versions of the software:

  • Confluence 3.2-rc1 (release candidate 1)
  • Copy Space plugin 1.2
  • Gliffy plugin 2.0.2-RC2

Drawing diagrams on a wiki page

Recently I’ve been drawing some diagrams in our technical documentation. This is a part of technical writing that I’ve always loved. Since our documentation is housed on a wiki, we have a couple of choices for creating diagrams. We could use a dedicated graphics program such as Visio, PowerPoint or SmartDraw, then convert the diagram into a JPEG, GIF or PNG image and upload it onto the wiki page. Or we can use Gliffy to draw directly on the wiki page. I think Gliffy is pretty magical, so I decided to blog about it here.

The need for diagrams seems to go in spurts. For a while all you need is words and screenshots. Then suddenly there’s a barrage of complex concepts, where a diagram works so much better than a web of words. I figure that if I start scribbling circles with connecting lines while getting the SME to explain a concept to me, then my readers will probably be grateful for a diagram too.

Why do I think Gliffy is magic?

We’re using Confluence wiki for our documentation. Gliffy is installed as a plugin on the Confluence server. What makes this magical is that anyone who has permission to update the wiki page can also update the diagram. There’s no need for extra software, just a web browser like Firefox or IE. Also, if I happen to be working from somewhere other than the office or my laptop, I’m not stuck without my drawing program. I can just log in to the wiki web site and scribble away.

Another reason for blogging about Gliffy right now is that I’ve just discovered two features in Gliffy that I didn’t know about before:

  • You can include screenshots or other raster images into your diagram.
  • You can hyperlink parts of the diagram. Gliffy will generate an image map for you.

Some examples in our documentation

When I realised that you can include a screenshot and make an image map (duh Sarah, that took a while) I tried it out by creating a diagram as an overview of a user guide. Here it is: Gadgets and Dashboards User Guide, still in beta but published to the whole wide world. Clicking the callouts will take you to the relevant section of the documentation.

Here’s a diagram that I created after getting the low down from an engineer on a complex subject. The diagram gives an overview of caching in Crowd, our user management and SSO product.

Gliffy as a drafting tool

Our Design team used the Crowd caching diagram, that I created in Gliffy, as a basis for a pretty picture to include in the Crowd 1.6 release notes.

The drawback (heh, no pun intended; spotted while proofreading) of the awesome picture in the release notes is that it would be time-consuming to edit and the Design team uses software that the technical writers don’t have. That’s OK for release notes because you don’t plan to update the diagram once the release notes have been published. But where there’s the possibility of ongoing maintenance, it’s safer and simpler to use a tool like Gliffy that supports editing the diagram as part of the wiki page.

What Gliffy looks like

Gliffy diagrams appear as JPEG images on the wiki page. If you have permission to update the wiki page, you’ll see an “Edit Diagram” link below the diagram. If you click the link, the Gliffy editing screen opens, looking like this:

Drawing pictures on a wiki page

Drawing diagrams on a wiki page

Here’s a thumbnail of a larger version of the same screenshot — click to expand it if the one above is difficult to read:

Drawing pictures on a wiki page

Drawing diagrams on a wiki page

As you can see, Gliffy looks very similar to the graphic tools we know and love. On the left are the different categories of shapes that you can drag onto your canvas. In the middle is the canvas you are working on. At the top and on the right are various tools and properties.

Tip: (This is the bit I didn’t realise until recently.) If you want to include an existing image into your Gliffy diagram, just upload that image (as a JPEG file) onto your Confluence page. It will appear in the list of images in the “Page Images” section on the left. Then you can drag it onto your Gliffy canvas.

Other wiki drawing and graphics tools

I don’t use any other wiki drawing tools at the moment, but I’ve had a look around because it’s interesting to see what is available.

For Confluence wiki:

  • I’ve heard a lot of good things about Balsamiq Mockups. People use it at Atlassian, where I work, to create screen mockups and feature specifications.
  • The Chart plugin displays various chart types and graphs, based on tables on the wiki page or attachments to the page. This is not a drawing tool, but it does display flowcharts and graphs based on editable content in the wiki page.
  • The Confluence UML Sequence plugin lets you generate UML sequence diagrams using the free service at http://www.websequencediagrams.com/.
  • The Graphviz plugin displays graphs based on Graph Visualization Software (Graphviz) and the DOT language. Again, this is not a drawing tool, but it does display flowcharts and graphs based on editable content in the wiki page.
  • The Whiteboard plugin lets you insert a whiteboard onto your wiki page, so that you can write up your meeting notes in a sort of sticky or Post-it format.

I don’t know much about other wikis. A few searches yield the following:

A BTW: When I was doing the above searches, it was often difficult to find the detail I needed because the web sites kept offering me videos and marketing blurb about how to use the wiki for various use cases and high-level feature overviews. My recommendation for all web site designers: Put a link to the technical documentation in a prominent place on all web site pages! Or include a search that encompasses the tech docs. Few people are as tenacious as I am when looking for a specific low-level feature requirement. Most will just go away after a couple of clicks.

Dear reader 🙂

If have you used any of the above tools for drawing diagrams on wiki pages, I’d love to know what you think of them. Do they do the job to the level that a technical writer requires, and do you know of other tools for drawing on a wiki page?

%d bloggers like this: