Tweet at us now – Sydney technical communicators meeting at Atlassian on 4 May

The next meeting of the Sydney CBD technical communicators group is on Wednesday 4 May. This month it will happen at the Atlassian offices, and I’ll be presenting a session on Twitter in and around your documentation. Can you come? Lunch is on the house! Even if you’re not in Sydney, it would be great if you can tweet at us: #SydneyTechComm. Tweet now, or any time before the meeting. I’d love to show the group a stream of tweets from technical communicators all over the world.

Thank you to Bede Sunter for all his hard work in arranging these great monthly sessions! He has asked me to speak this month, and we’re holding the session at the Atlassian offices.

Date and time: Wednesday 4 May, 12:30 to 1:30pm.
Place: Atlassian offices, 173-185 Sussex Street, Sydney. (Google maps.)
Lunch: Free. Thank you Atlassian!
Who can come: Anyone interested in technical communication.
RSVP: Drop a comment on this blog post, and I’ll email you.

The presentation

You can download the presentation from SlideShare.

I’ll give a talk about using Twitter in and around your documentation.

A little bird told me… about a good page in your user guide

What’s all the fuss about Twitter, and how can I get involved? Do I even want to? In this session, Sarah will give a quick introduction to Twitter and the conventions that have sprung up in the tweeting community. Then we’ll see how we can use this new medium in and around our documentation:

• Twitter as a medium for release notes.
• Encouraging your readers/customers to tweet hints and tips.
• Building interaction into your documentation pages.

Come along, bring your smart phones and your clever quips. Let’s get social.

I’m trying something new, in that I’ve already published the slides on SlideShare. This means you can have a look even before the session happens. Let me know if you like seeing the slides early!

Tweet hello to the Sydney technical communicators

At the session I’ll be introducing a number of people to Twitter.

• If you’re planning to come, tweet now.
• Even if you’re not in Sydney, it would be great if you can tweet at us. I’d love to show the group a stream of tweets from technical communicators all over the world. You can tweet now if you like — the tweets will show up in the Twitter stream next week too.

If you haven’t used Twitter before, you can sign up for a free account at the Twitter website . You can use any name you like. It doesn’t have to be a real name.

Say hello and tell us where in the world you are, using this hash tag:

#SydneyTechComm

Some example tweets:

Looking forward to the Sydney tech communicators meeting on 4 May http://bit.ly/iEzdkV #SydneyTechComm

Sydney technical communicators tweetup 4 May FTW http://bit.ly/iEzdkV #SydneyTechComm

Hello Sydney technical writers! From a chilly Mark Twain in San Francisco #SydneyTechComm

Let me know if you can come or if you can tweet

Add a comment to this post, if you like. I’d love to see you there, or see your tweet!

Categorising your wiki spaces

If you’re anything like us, your Confluence site has a large number of spaces. This can be confusing for readers, especially when they see a long list of spaces on the dashboard with no easy way of selecting just the spaces that are relevant to them. There’s a way to categorise your spaces so that readers can choose the subset that they are interested in. I’ve started organising the spaces on our documentation wiki — here’s what I’m up to.

In brief: Decide how you want to categorise your spaces. Then go to “Space Admin” > “Space Labels” for each space and add the relevant “space category”. Now your readers can see a categorised list of spaces on the dashboard and in the space directory.

I’m using Confluence 3.5.2. The space directory and space categories were introduced in Confluence 3.5.

Categorising the spaces

Our documentation wiki has a number of spaces containing user guides for each product. The wiki also has a set of spaces containing developer guides, as well as a number of spaces that do not contain technical documentation.

It therefore makes sense for us to have at least the following categories:

• A category called “documentation”, listing the latest documentation spaces for each product.
• A category called “development”, listing the spaces containing API and plugin guides for developers.
• A category for each product, such as “JIRA”, “Confluence”, “Crowd”, and so on.

The categories are fluid to some extent. People will add new ones and remove obsolete ones as time goes on.

Adding a space to a category is the same thing as adding the category to the space.

• Go to “Browse” > “Space Admin”.
• Click “Space Labels” in the left-hand navigation bar.
• Type the category under the heading “Space Categories” and click “Add”.

Categorising a space (click image to enlarge)

The space directory

The “space directory” is visible to all readers of the wiki. Just click “Browse” > “Space Directory”. People can choose to see all the spaces, or to limit their list to just one category. They can further reduce the list by typing text into the “Filter” box.

Here’s our space directory as at today showing the “Documentation” category. I’ve added spaces into that category just by adding the space category “documentation” to each space, as described above.

The "Documentation" category on our wiki

Here’s the “Development” category:

The "Development" category on our wiki

Categories on the dashboard

Now that we’ve categorised our spaces, people can choose to view the spaces by category on the dashboard too. Here’s the list of spaces on the dashboard, with the “Category” tab and the “Documentation” category selected.

Categorised spaces on the dashboard

Here’s the list of recent updates on the right-hand side of the dashboard, with the “Space Categories” tab and the “Documentation” category selected.

Recent updates for spaces in the "Documentation" category

Seeing it in action

Here’s a link to the space directory on our documentation wiki and the dashboard.

More ways of using space categories?

Space categories have been around for a while in Confluence. In an earlier incarnation, they were called “team labels”. Up to now, they haven’t been used for very much. Even now, the functionality built on them is cool but not immensely exciting.

I guess you can see Confluence in two ways. One is as the web interface and supporting backend, as supplied by Atlassian. The other is as an extensible platform that plugin developers and API programmers can build upon.

So… now Confluence has “space categories”. Are there any exciting things we could do with this metadata, particularly from the point of view of Confluence as a documentation platform? Hmmm…. thinking….

Test-driven API documentation

My latest interest is in innovative and useful ways of doing API documentation. In a comment on a stackoverflow post, Aaron Digulla suggests that we should use tests for the example code in our API documentation.

Here’s the relevant part of Aaron Digulla’s comment:

In my case, I use two tools:
1. A Wiki to give you the big picture… [snip]
2. Lots of tests which show how you can use the code. You need to write them anyway, so write them just like any other code (clean and readable) and turn them into your examples. Main advantages: Documentation can lie, be wrong or be outdated. Tests Always Tell The Truth (TATTT).

Now, that sounds interesting!

Has anyone else tried this, and do you have any examples that we can take a look at? It would be great to hear how well it works. For example, I wonder if the granularity of the tests matches the granularity required for documentation examples. How do you pick the tests that are relevant for the documentation?

All comments greatly appreciated.

Going off topic: It’s been a while since we’ve had a tree in one of my posts. Here you go:

Two Rainbow Lorikeets lending colour to a dead tree outside my window

JIRA cloning to create a template for repeated documentation tasks

At each major release of the software that we document, a technical writer has to perform a number of tasks. Many of the tasks are repeated at every release. My team uses JIRA to keep track of our documentation tasks. Last week I decided to try using JIRA’s cloning functionality to create a template, consisting of an umbrella issue with a set of subtasks, that we can clone for future releases. It’s looking like a useful idea, so I’m blogging about it in case other people find it helpful too.

JIRA is a bug-tracking and project management tool. Up to now, when preparing for a release we’ve created the documentation tasks in JIRA by basing them on the tasks from the previous release. This worked well, but we did spend a fair bit of time sorting out which tasks were required for every release, as opposed to the feature-related documentation bound to a specific release. We also had to remove comments like “Completed this task on Monday 1 April,” or “Reviewed by PM and dev.”

What is JIRA cloning?

In JIRA, you can clone an issue (task) to create a copy of the useful parts of that issue. When you clone the issue, JIRA creates a new issue with the same summary (title) and description as the one you’ve cloned. It copies across the information from other relevant fields and sets the status of the new issue to “open”. The JIRA documentation lists all the fields that are copied to your new issue.

You can also choose to clone the subtasks — and that’s where it gets really handy!

Creating the template for documentation tasks

To create my template for use in future releases, I cloned my documentation task from the previous major release plus all its subtasks.

Then I deleted the subtasks that related specifically to the past release. I was left with an umbrella issue and a number of subtasks, one for each of the tasks that need to be done at every release.

Next I adjusted the issue summaries and descriptions to make them generic, so that they no longer refer to any specific release number.

Now that we have a template that other technical writers will be using, I decided to expand the descriptions too. It’s useful to include a bit more explanation than I have done in the past, when the descriptions were mostly just a reminder to myself of what needed doing.

Here’s that our umbrella template issue looks like now. The product I’m documenting is called “Confluence” and I’m using the convention “x.x” to indicate a release number that needs to be filled in when we create a real issue based on the template:

A JIRA issue used as a template

Below is a list of all the subtasks on the above issue. We will use each of the subtasks as a template too:

The subtasks on our JIRA template issue

This is an example of one of the subtasks:

A JIRA subtask to be used as a template

As you can see, the subtask contains quite a bit of detail about what needs to be done.

You’ve probably also noticed that all the issues have a status of “Resolved”. I did that just so that the template issues don’t keep popping up and demanding to be addressed. But when we clone the issues at our next major release, JIRA will automatically give the new issues a status of “Open”.

Using cloning to prepare the documentation tasks at our next release

At the next major release, we can just clone our umbrella template issue and say “Yes, please” when JIRA asks if we want to clone the subtasks too.

We will then go on to add more subtasks to our new issue. They will be the tasks specific to the release, such as documenting new features and changes to supported platforms. The template issues will remain untouched, ready to be cloned again next time round.

No doubt we will find tasks and improvements to add to our template issues from time to time as well.

The benefits of having a task template

This will save us a lot of time: A couple of hours per release!

The template will help us make sure that we don’t forget any of the things that need to happen at each release. It will also give new team members a concise overview of what’s involved in a documentation release.

The template also gives the product managers and development team a good insight into the tasks that the technical writers need to do in order to publish and maintain the documentation. Many of the repeated tasks revolve around ensuring that we have version-specific documentation for customers who do not upgrade to the latest release, supplying downloadable versions of the documentation for customers who cannot use our online documentation, updating the tutorials that are shipped within the product itself, and generally keeping the documentation ticking along.

It’s not uncommon for people, other than the technical writers, to overlook this sort of necessary but behind-the-scenes task.

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.

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:

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:

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.

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.

• In the JIRA documentation: Connecting to an LDAP Directory.
• In the Confluence documentation: 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:

A reusable Gliffy diagram

Reusing the diagram:

• This page in the Confluence documentation uses the above diagram: Connecting to Crowd or JIRA for User Management.
• The related page in the JIRA documentation uses the same diagram: Connecting to Crowd or Another JIRA Server.
• So does this page: Diagrams of Possible Configurations (Confluence).
• And this page: Diagrams of Possible Configurations (JIRA).

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!

_LDAP Connection Pool Settings