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









