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?

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 4 July 2009, in Confluence, technical writing, wiki and tagged , , , , , , , , , , . Bookmark the permalink. 28 Comments.

  1. Hey There,
    We have just started to use Gliffy quite a bit at Optus doing screen mock-ups for rapid prototyping of web-based applications we build for our internal customers. It’s been working well.

    The hard thing about Gliffy is some users expect some level of interactivity form the prototypes. Eg. They want to be able to click and see what would change on a screen… So not only do they want to prototype the screen layout, but to also prototype the screen flow…

    Interesting to see where it all heads!
    Sherif

  2. This looks ace.. I could use this for wire framing web site concepts.

  3. Hallo Sherif and Utopie Design

    Gliffy for rapid prototyping of screens and web site design — awesome. Sherif, I really like your point about making the prototypes interactive. Gliffy (or Balsamiq Mockups) would need to add some basic scripting capabilities, sort of like what you can do in PowerPoint. Now, that would be awesome!

  4. @Sherif You could link from one Gliffy diagram to another. To do this, you would create links on the clickable areas of the mockup using the tiny urls of pages that had the ‘detail view’ Gliffy diagrams on it.

  5. Thanks for the review and compliments about Gliffy. We really appreciate all of the feedback! If your teams are using Gliffy 2.0.1 you’ll see our refreshed user interface and new network symbols — have your teams considered using Gliffy Plugin for JIRA? We’d love to know if you see a fit for that or if Confluence drawing is where you tech writers focus. Thanks again,
    Best!
    Debi K
    Gliffy

  6. Hallo Debi

    Great to hear from the Gliffy team! I hadn’t thought much about using Gliffy in JIRA before, although I did know that the plugin exists. But now that you mention it…

    Every now and then, when creating a JIRA issue for a new feature or a new documentation set, I do find myself drawing a diagram on the wiki to illustrate a point, and then adding a link in the JIRA issue pointing to the wiki page that contains the diagram. In such circumstances, Gliffy in JIRA will be useful, because then you’d have all the information about the feature request in one place.

    But as tech writers, it’s fair to say that we work on the wiki for most of the day🙂

  7. OptionsTrader

    Hey Guys,

    I’m wondering if anyone can help me with a challenge I’m facing along the lines of this discussion. This has to do with a project I’m in charge of for my company’s Wiki page.

    My goal is to put a Power-Point flowchart onto my company’s Wiki page, so that different ‘bubbles’ are click-able and link to other pages within the Wiki. Do you know if Wikipedia would support this functionality? Would this possibly work better with an application besides Power Point? Any tips/advice? I’m not incredibly tech-savvy, so any help is greatly appreciated.

    Thank you so much,

    Blake

    • Hallo Blake

      I’m not very clued up on MediaWiki, and I’m assuming that your company is using MediaWiki because you mention Wikipedia. I don’t know how deep MediaWiki’s integration is with PowerPoint, i.e. whether you could click a link in a PowerPoint slide to go to another wiki page.

      A good place to get answers might be one of the MediaWiki forums, like this one:
      http://mwusers.com/forums/

      If MediaWiki doesn’t allow what you want, then you could investigate using a straight image map. That’s the basic HTML way of doing it. If you export your PowerPoint slide to HTML, it may even create an image map for you. Then you may be able to add the HTML directly onto your MediaWiki page.

      If the PowerPoint export does not work, then you could build your own image mage quite easily, with something like CoffeeCup:
      http://www.coffeecup.com/image-mapper/
      It used to be free, but not any more. There are probably other freeware image mappers out there too.

      To get the clickable parts of the Gliffy diagram I mentioned in the blog post above, I used Gliffy to highlight the sections I wanted clickable. Then Gliffy generated the image map for me. (You can see the image map if you view the HTML source of the User Guide page linked above. It’s an HMTL element that starts with “<map name=…".)

      Good luck! I'd be interested to know WikiMedia's support for this requirement!

      Cheers
      Sarah

  8. Hi Sarah

    Catching up on some long overdue reading… I loved this comment you made:

    “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.”

    I’ve done exactly that many times — taken my scribbles and made a flowchart or swimlane diagram or similar out of them, then added them to the user docs. Like you, I figure that if a diagram helps me to understand the connections, then there have to be some of my readers who will learn better that way too.

    Thanks for stating it so eloquently.

    –Rhonda

  9. Hallo Rhonda, and thank you.🙂 Good point that some readers learn better visually. Diagrams take a bit of time to make, but it’s great if they save our readers time. Oh, to be a fly on the wall and hear the “Aaah, now I see”!

  10. Does text in Gliffy drawings appear in search results?

  11. Hallo Richard
    Cool question! No, it doesn’t. I didn’t know the answer, but have just tested it by searching our Confluence documentation. I searched for a word that appears as text in a Gliffy diagram in the Crowd documentation. I restricted the search to the Crowd space, and to attachments only (because the Gliffy diagram’s data is stored as a page attachment). The search did not pick up the relevant attachment.
    Cheers, Sarah

  12. Hello Sarah,

    I just noticed your blog entry about image maps in Confluence. I’d like to do just that, create a block diagram and make the blocks in the diagram clickable. To that end i downloaded a trial of confluence (was using mediawiki so far), but am not sure how to make a clickable image. Can you perhaps provide some hints or links to that.

    thanks,
    Daniel

    • Hallo Daniel

      We use Gliffy to create image maps in Confluence. Gliffy is a plugin for Confluence, developed by a third party. It’s not part of the default Confluence installation. If you want to use it, you need to download it and install it into your Confluence wiki.

      You need administration rights to install a plugin into Confluence. You can install Gliffy via the Confluence Plugin Repository. Here are the instructions:
      http://confluence.atlassian.com/display/DOC/Installing+and+Configuring+Plugins+using+the+Plugin+Repository+Client

      If for some reason you can’t use the Confluence Plugin Repository, you can download the plugin from the Atlassian Plugin Exchange:
      https://plugins.atlassian.com/plugin/details/254

      Here’s the Gliffy web site:
      http://www.gliffy.com/

      Gliffy offers a free evaluation period. If you do decide to use it, you’ll probably need to buy the plugin, depending on your usage. Here is their information about the various licences available:
      http://www.gliffy.com/confluence-plugin/licensing.php

      I think it’s well worth it.🙂

      If you decide against Gliffy but are willing to enable the {html} macro, then you could add a standard HTML image map into a Confluence page. The {html} macro is installed in the default Confluence installation, but is disabled because of security concerns. See this page:
      http://confluence.atlassian.com/display/DOC/HTML+Macro

      Cheers
      Sarah

      • Chris Bradshaw

        Hi….

        You must be tired of being asked about this….but I have some similar questions to the above……

        I have installed trial versions of confluence and gliffy. It works great except for creating a clickable Image Map…..I can’t see any option for selecting an area of a drawing and assigning a URL to it.

        Might it be because I am using trial versions?

        Or is there an additional plugin (or plugins) which I need to get image map functionality?

        Thanx muchly in advance.

        Chris.

      • Hallo Chris

        Gliffy offers a link on a text box and on the text words themselves. So if you want to put a link on an image, I guess you could put an empty text box over the image. I haven’t tried that. When you select the text box, or one or two words, then the word “link” and a link icon appears in the right-hand panel, in the “Text Properties” section.

        I hope that helps.🙂

        Cheers
        Sarah

      • Sarah is right!
        Text as link is the only option for URL linking at this time.
        I have made a text box the size of a shape and matched the colors of the shape and text. This enables a ‘ghost’ text link.

        Email me support at gliffy dot com if you have ongoing troubles wit the linking,
        Debi K
        Gliffy

  13. Hi,

    I was excited when I first read your article, because I could really need to create image maps directly into confluence using Gliffy.

    However, I don’t understand how to do it. It seems to me that what you are talking about is text as link, and that this is the only option at the moment?

    Am I right?

    Thanks!

    Sven

    • Hallo Sven
      Yes, that’s right. As far as I know, the only option is to link to the text. You can superimpose a blank text box over an image, to simulate linking from an image.

      It’s definitely worth checking the latest release of Gliffy, though, to see if they have added the link-from-image feature. They are aware that it would be very useful!

      Cheers
      Sarah

  14. Using a newer version of Gliffy than was available for any of the previous comments.
    Gliffy Version 3.5.2

    The ‘blank text box’ suggestion does not appear to work. And, adding text only for the sake of adding a hyperlink is burdensome.

    Ideally, each object could have a hyperlink applied to it. This would be Very useful. Are there plans to add this feature?

    This is a problem with prezi too. Maybe it’s too much effort to build?

  15. Hi Sarah,

    I’m looking very much forward to buy your book when it’s possible to get it in PDF format. I like to travel light, enjoying reading books on my Adam (http://www.youtube.com/watch?v=-9G22c8DmGI&feature=related) – is uses a display that enables you to read stuff on bright daylight.

    Any update on when we can enjoy ebook / PDF?

    I’m part of an Open Source group that develops software for an ancient portable – we use Atlassian OnDemand, so I’m looking forward to some nice inspiration in the upcoming webinar.

    Best regards
    Gunther

    • Ups – sorry – wrong thread – was meant to be a reply to the webinar…

      /G

      • Hallo Gunther

        Heh heh, I’ve found the comment even though it’s on this thread.🙂

        Thanks for your nice words about the book and the webinar! The book will be available in ebook format (Kindle and EPUB) but not in PDF. I think your ADAM reader should be able to read EPUB format. Richard Hamilton at XML Press is working on the ebook formats. He’s @RichardHamilton on Twitter.

        It’s great that you can make it to the webinar. I’m looking forward to “seeing” you there! I haven’t included anything in the webinar about ancient portables.😉

        Cheers, Sarah

    • If you still need PDF and all that is offered is epub, Calibre will convert epub to PDF (with much more control than most converters).

      http://calibre-ebook.com/

  16. Everything said made a bunch of sense. However, what about this?
    what if you were to create a killer post title? I am not saying
    your information isn’t good, but what if you added a title to possibly
    get a person’s attention? I mean Drawing diagrams on a wiki page | ffeathers is kinda vanilla.
    You ought to glance at Yahoo’s home page and note how they create article headlines to get viewers to open the links.
    You might try adding a video or a related pic or two to grab readers
    excited about what you’ve got to say. Just my opinion, it would bring your blog a little livelier.

  1. Pingback: Keith Soltys (ksoltys) 's status on Saturday, 04-Jul-09 13:51:17 UTC - Identi.ca

  2. Pingback: Solving a problem with the Confluence Copy Space and Gliffy plugins « ffeathers — a technical writer’s blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: