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 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 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:

• TikiWiki has a feature called Drawings that lets you create and edit drawings.
• MediaWiki has a number of promising diagram extensions.
• TWiki has the TWiki Draw plugin and the Chart plugin.
• I couldn’t find any information on drawing or diagram tools for PBworks, MindTouch Deki, Jive SBS (formerly Clearspace) or SocialText.

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?

Writing a guest blog post

Scott Nesbitt has asked a number of technical writers, and I’m one of the privileged, if we’d like to write a guest post on the DMN Communications blog. So I did: What makes a technical writer tick?

Writing for someone else’s blog is fun! It’s also interesting.

What’s different

You suddenly have all sorts of new considerations. You don’t know exactly when your post will be published. Potentially, you don’t know your audience as well as when writing on your own blog. You’re not sure how much editing the blog owner will do on your post after you’ve submitted it. You don’t have hands-on control of the formatting and you can’t make final tweaks just before publication.

Publication date arrives

I waited with bated breath. Seeing my post appear: Fun — almost as if reading it for first time. Surprise — the format is unfamiliar. Even though I’ve visited DMN Communications often before, it was still odd to see my words up there in that format. When writing on your own blog, you write in a WYSIWYG editor. You craft the appearance along with the words.

Hmmm. That’s the way most of us operate in our day jobs too. This made me think again about the trend towards content reuse and single sourcing, such as via DITA, where you need to write format-agnostic content. It’s difficult!

From the point of view of the blog host

On the subject of inviting guests to blog on your site, Scott has written some interesting notes from his perspective.

Scott added some headings into my post. That was a good editorial decision. He also let me know that he had done it before he published the post. He added the image at the top, and then added my fish image at the bottom when I emailed it to him later. Awesome to-ing and fro-ing. Scott also let me know how much extra traffic my post had generated. That was cool. Thanks Scott!

Comments from readers

I’m thoroughly enjoying the comments other technical writers are leaving on the post. Who can resist the “fish called Rhonda“? Bring on the puns, guys and gals! And if you want to add more serious stuff, well, that’s OK too

Writing a guest blog post

Technical writers are simply the best. Better than all the rest. With another bow to Douglas Adams: It is a bizarrely improbable coincidence that anything so mind-bogglingly useful could have evolved purely by chance.

Twitter as a medium for release notes

In the last couple of weeks, I’ve been trying an experiment — using Twitter as a medium for release notes. It’s been interesting, so I thought you’d like to read about it. We could use Twitter in other ways related to technical documentation too, such as hints and tips or FAQs. Let me know if you’ve done that already!

I’m going to start with a short introduction to Twitter, mentioning particularly the aspects that I found useful when tweeting release notes. If you’re already a twitterologist, you may want to skip that bit. Then I’ll describe how we’ve used Twitter as a method of communicating the highlights of our release notes.

An introduction to Twitter

Twitter is a service that allows you to send short messages to anyone who is interested in reading them. You can sign up for a free account at http://twitter.com. Then just type in your message where Twitter asks somewhat abruptly “What are you doing?” and click “Update”. Bob’s your uncle, you’ve tweeted.

Tweets

“Short” messages? Oh yes, very short, especially in technical writing terms The maximum length of each message, or tweet as they’re called, is 140 characters. There’s an art to saying something meaningful in such a short message. Especially when the message is a release note highlight. So be warned, you may spend quite a bit of time tailoring your tweet.

The tweet below illustrates a number of conventions tweeters use to make as much as possible of those 140 characters. I’ll tell you more about the conventions later, and how we can use some of them in our tweeted release notes.

Twitter as medium for release notes

Followers

According to some reports, there are approximately 10 million people using Twitter, and its growth rate is around 1,382 (more than a thousand) percent per year. (See Web Strategy blog.) That’s an awful lot of tweets to read. So what you do is “follow” people. Twitter will send you the tweets of the people that you are following. Similarly, other people will follow you so that they can read your tweets.

You can restrict the visibility of your tweets to only people you’ve allowed to see them. You can also block specific people from following you.

RT (retweet)

What I’ve found extremely interesting in Twitter is the conventions that have sprung up as people start using it for wider and more specific purposes. “Retweeting” is one of those conventions. If you like what someone said and want to spread the word while attributing the goodness to the original tweeter, you can “retweet” their message. Simply add the letters “RT” into your message, copy the original text, and tweet away. What’s more, there are Twitter clients that do this for you automatically. I’ve mentioned some clients later in this blog post.

In the tweet illustrated above, Alister Scott has retweeted one of my tweets. Thank you Alister

@ replies

When you want to reply to someone, or refer to them in such a way that they’ll know you’re doing it, include an “@” and the person’s Twitter username. For example, “@sarahmaddox”. Many clients provide a “reply” option that does this for you. Clients also have a separate column or tab showing the @ replies directed to you, so that they don’t get lost in the main stream of tweets.

#-tags and search

Another very useful convention is the #-tag. Let’s say you are sending a message about a particular subject, and you think other people would like to read and to send tweets about that subject on an ongoing basis. This may be for fun or for a more serious purpose. Just think up a keyword, prefix it with a “#”, and include it in your message.

In the tweet illustrated above, I used “#googlewave”.

Here are the realtime results for a Twitter search on “googlewave”. And here’s what people are saying right now about “funnywords”.

Other people will start using your keyword, and they will also search Twitter for other messages that contain the same keyword. Many Twitter clients will do the search for you. Twitter search returns results from all tweets sent by anyone in the whole wide world, not just the tweets sent by people you are following.

Combined with the #-tag, this makes a very interesting combination for our tweeted release notes.

Short URLs

A URL can be very long, consuming far too many of those valuable 140 characters. Luckily there are a few services on the web that will shorten your URL for you. The service gives you a short string that you can include in your tweet (or in an email, or a blog post, etc). When other people click the short string, they are bounced back to the service’s URL and then forwarded on to your original URL. Examples of such a service are TinyURL.com, bit.ly and tr.im.

In the tweet illustrated above, I used TinyURL.com.

Twitter clients

One of the most magical aspects of Twitter is that you don’t have to go to Twitter.com to use it. There are a number of Twitter clients that add useful functionality to your desktop and make it possible to tweet from your phone too.

The clients have built in extra functionality as the Twitter culture evolves:

• The use of a #-tag triggers an auto-link. If you click the link, it launches a Twitter search.
• The use of “@username”, e.g. “@sarahmaddox”, links to the user’s Twitter profile e.g. mine.
• Clients like TweetDeck provide sophisticated search functionality. You can define search criteria using AND, OR, quotes, etc and build a “permanent” search that notifies you whenever a new tweet arrives matching your criteria. The matching tweets can be from anyone, so they’re not restricted to your friends.
• Clients supply an easy way of shortening URLs. Some clients do it automatically, via a specific URL-shortening service like TinyURL.com, bit.ly or tr.im. Other clients offer you a range of services to choose from.

I have TweetDeck running on my Windows XP desktop and on my Windows Vista laptop. It’s built on Adobe Air and has a lot of useful features including a sophisticated search capability. Here’s what it looks like. In the left-hand column are some tweets from people I’m following. Next are replies sent to me (via “@sarahmaddox”). The two right-hand columns are specific searches I have set up. All this is configurable, including the order of the columns:

Twitter as medium for release notes

TweetDeck gives a handy notification when new tweets arrive from people you are following, or as replies to you, or that match your search criteria:

Twitter as a medium for release notes

Want to read and send tweets from your phone? Well, you can. On my iPhone, I have both Twitterific and TwitterFon. I prefer TwitterFon — see screenshot further down this blog post.

You can also send tweets to Twitter via SMS. That’s what I did before I got the iPhone. So at least you can tell people what you’re having for dinner, even if you can’t read what they’re having until you get back to your computer

Tweeting our release notes

So, how can we make use of all the above features and conventions to use Twitter as a medium for our release notes?

Aim

To emit a tweet per major highlighted point in the release notes, to include a link to the release notes and to provide a way for tweet consumers to see a collection of such related tweets.

A consideration

In general, people read only the last few minutes’ worth of tweets. It’s not like email, where people make an effort to at least scan their inbox when they’ve been out of touch for a few hours or days. We need to make sure our design catches as many people as possible, and shows them where to go for more information if they want it.

What we did

Here’s the plan of action:

• Use Atlassian’s corporate Twitter account, rather than a personal account. Release notes are in a weird place, partly technical documentation and partly marketing information. People follow Atlassian’s Twitter ID and know what to expect from it i.e. company news. So they’re not dismayed to receive marketing-type information.
• Use a #-tag to tie the tweets together. This is the most exciting bit. It provides a way for tweet consumers at any time to see a collection of such related tweets. A collection of release highlights is… the release notes. Ta da ♪ ♫
• Use a shortened URL (e.g. TinyURL.com, bit.ly or tr.im) to link to the release notes themselves, so that people can read the full details if they want to.
• Don’t send out all the tweets at once. This would spam people, and a number of other people would miss out on your news because they’re not reading their tweets at the time. Instead, send out two tweets a day, the second about four hours after the first, for two or three days.
• Try it out for three or four product releases, then assess feedback and decide whether to continue.

The results

So far, I’ve tweeted about two of our product releases: the Atlassian Eclipse Connector 1.0 and Confluence 3.0.

For the Eclipse Connector 1.0, I used a tag of “#EclipseConnector10″. (#-tags are not case sensitive, because the Twitter search is case agnostic.) Here’s a screenshot of the resulting search on the Twitter.com web UI, at a particular point in time:

Twitter as a medium for release notes

In the above screenshot, you can see the format we’re using for each tweet: the text of a highlight from the release notes, plus the #-tag (”#EclipseConnector10″) plus the short URL (”http://bit.ly/4mTLf”). Here’s the full content of one of the tweets:

Manage your Crucible code reviews via Eclipse Mylyn’s task-focused interface #EclipseConnector10 http://bit.ly/4mTLf

Of course, the search may or may not show something quite different if you click it now.

What’s interesting is that I tweeted using the Atlassian account (the tweets with the dark blue icon of a dude holding up  slice of the globe) and other people retweeted or just repeated the tweets. ‘Coz they liked them. Those are the entries with “RT” in the above screenshot.

For the Confluence 3.0 tweets, I used the tag “#Confluence30″. Here’s a screenshot of the resulting search on the Twitter.com web UI, at a particular point in time:

Twitter as a medium for release notes

And here’s a screenshot showing the resulting search via TwitterFon on the iPhone:

Twitter as a medium for release notes

And you can check what the search yields now.

Nothing can go wrong go wrong go wrong

Heh heh. Take a close look at the two screenshots above. One person “hijacked” our #Confluence30 tag to communicate a problem he had when upgrading to the new version of Confluence, and the workaround for the problem

Of course, it was totally foreseeable that people would tweet problems as well as praise, and would include “our” #-tag in their tweets. Nothing is sacred on Twitter. We decided it would be interesting to go ahead and see the sort of response we get. After all, people are saying all sorts of things about us all the time, on and off Twitter.

The iPhone screenshot above shows the same person’s problem tweet, plus another person who was letting people know about a particular feature in the Confluence release (Twitter-like status updates).

It’s been a fun and interesting experiment.

Other uses of Twitter

People are getting very creative with Twitter. Wikipedia lists some of the unusual situations where Twitter has proved useful.

As technical writers we can probably think up a gazillion ways to use Twitter. We could tweet hints and tips, or even FAQs if we’re super wordsmiths, using the #-tags and shortened URLs much as I’ve shown above. Have you tried this or anything similar?

AODC 2009 wrapup

Last week I attended the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. This is the second year that I’ve been to this conference, and I highly recommend it for anyone interested in technical writing or communication.

A big “thank you” to the AODC organisers, and especially to Tony Self, Penny Bradley and Mick McMahon. The conference ran without a hitch. It’s worth attending just for the social events and networking. As a bonus, the speakers and sessions were interesting too

There were 19 sessions in total. I have blogged about some of them:

• Pattern language for information architecture
• Content, standards, learning and SCORM
• Delivering enterprise software documentation on a wiki
• Design of context-sensitive help
• Translation and localisation
• Single source publishing
• Structured authoring
• Stump the panel
• Enabling feedback and collaboration in online help systems
• What if the reader can’t read?

Melbourne

Never been to Melbourne? Neither had I. It’s a fun city, and quite different in character to Sydney. The AODC conference happened at the Vibe Savoy hotel. Here’s the view from my hotel window, overlooking the Southern Cross Station out towards Docklands:

AODC 2009 wrapup

Here’s the GPO and a Melbourne tram:

AODC 2009 wrapup

Next year’s AODC

I’ve heard that AODC 2010 will be in Darwin. I haven’t been there yet either. Hope to see you there

Mick McMahon

AODC day 3 – Pattern language for information architecture

Last week I attended the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. This blog post is part of a series about some of the AODC sessions I attended.

Here are some notes I took from the session on a pattern language for information architecture, by Matthew Ellison. I hope these notes are useful to people who couldn’t be at the conference this year.

Pattern Language for Information Architecture

Matthew introduced pattern languages by saying that they may give you a practical way of capturing the techniques that work for you — a way of documenting the golden rules.

A pattern language is a structured method for describing good design practices within a specific field. Michael Hughes has done a lot of work on pattern languages in our field. Pattern languages establish a rule of thumb. They do not offer a rigid solution, but something you can use again and again when similar situations arise in a particular environments.

Pattern languages in architecture

Pattern languages were first developed about thirty years ago, originating in the architecture field. Matthew was very taken with Christopher Alexander’s book A Pattern Language: Towns, Buildings, Construction (1977). It even smells nice, says Matthew. The structure of the book, its pictures and diagrams, and the quaint language make it a book you can dip into and enjoy. It covers a wide field, from the design of towns down to the design of doorknobs.

Matthew showed us an example pattern from the book: “A Place to Wait”.

• The pattern starts with the problem: “The process of waiting has inherent conflicts in it.”
• Then it proposes the solution. As an example of the quaint language used: the pattern suggests that you should “…fuse the waiting with some other activity — newspaper; coffee; pool tables; horseshoes… where you can draw a person waiting into a reverie; quiet…”
• Then there’s a really cute little sketch of what a waiting area might look like.

Pattern languages for UI design

Another field that uses pattern languages is user interface (UI) design. Matthew showed us what such a pattern formula (template) might look like. Once again, they start with a statement of the problem, then tell you where such a pattern would be used. Next the pattern offers a solution and some form of illustration.

One such pattern in UI design is “Pagination”. Matthew showed us how the list of pages at the bottom of Google search and various other sites all fit this pattern.

Pattern languages for information architecture

What do information architects do? There are a few definitions. A good one is that information architects are responsible for the overall organisation of content.

How can design patterns help? They allow content providers to apply tested architectures to improve the user’s experience.

Matthew listed the following types of design patterns:

• Interface and layout (window and page layout).
• Structure of information and navigation dynamics (TOC, related links, popups).
• Content (information types, writing style and the way we assemble the content we write).

An example of an information architecture pattern: “Breadcrumbs”. The problem is: Users need to know their location in the document’s hierarchical structure, so that they can browse back to a higher level in the hierarchy. Matthew showed us some examples of breadcrumbs in various applications.

Suggested components of an information architecture pattern:

• The problem.
• Usage (where the pattern is used).
• The solution (a short bulleted list that describes the golden rule — fairly flexible and not too prescriptive).
• An illustration.
• The rationale (the reason why you would use this solution).

Matthew took us through some more information architecture patterns: “Content taxonomy”; “Signposting”; “Popups”. I don’t have any notes from this part of the session — I got too wrapped up in watching the examples. Matthew is sure to have the details

Examples

Michael Hughes proposed a design pattern for contextual help, to determine when and how we might use such help. Matthew showed us an example of embedded help from Microsoft Excel that conformed to the design pattern.

We looked at some design patterns in a few state-of-the-art online documents. One example is the UK Daily Telegraph online newspaper. Matthew discussed the design objectives of this site, and how they might relate to online documentation too. Notice the design elements, such as:

• Signposting and visual breadcrumbs, near the top of the page.
• Search, always at the top. Search is very important in all online newspapers.
• List of related articles.
• Related RSS feeds.
• Link to in-depth background information that supports the story.
• Pictures.
• Link to feature article.

Comparing a sports report and a current affairs item, they are visually and spatially very much the same. This makes it easy to use these newpapers online.

We also looked at a government site showing UK planning and building regulations. It also has a standardised pattern, with each element in a predictable place.

How can we define our design patterns?

Matthew suggests the following steps:

• Create your pattern statements (problem, usage, solution, rationale, etc).
• Decide whether the pattern statements fit into a style guide.
• Decide whether to enforce your patterns, e.g. by building them into an XML schema or DTD.

There are different opinions about whether a design pattern would fit into a style guide. IBM talks about enforcing your design patterns in structured authoring via XML, e.g. as DITA topic specialisations or map domains.

Thank you for another very cool and informative presentation, Matthew.