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?