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?
[...] Drawing diagrams on a wiki page « ffeathers — a technical writer’s bl… [...]
Keith Soltys (ksoltys) 's status on Saturday, 04-Jul-09 13:51:17 UTC - Identi.ca
4 July 2009 at 11:51 pm
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
Sherif
5 July 2009 at 10:13 pm
This looks ace.. I could use this for wire framing web site concepts.
Utopie - Web Site Design Liverpool
5 July 2009 at 10:50 pm
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!
ffeathers
6 July 2009 at 5:49 pm
@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.
Jeff
7 July 2009 at 2:22 am
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
Debi K
10 July 2009 at 12:37 am
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
ffeathers
10 July 2009 at 8:40 am
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
OptionsTrader
9 August 2009 at 2:30 am
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
ffeathers
9 August 2009 at 1:00 pm
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
Rhonda
18 August 2009 at 8:39 pm
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”!
ffeathers
19 August 2009 at 9:26 am
Does text in Gliffy drawings appear in search results?
Richard S.
7 November 2009 at 8:40 am
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
ffeathers
7 November 2009 at 1:17 pm