Diagram guidelines

Diagrams can help clarify many articles. These guidelines tell you how to prepare diagrams to include in a wiki article. You'll probably also find the Wikipedia guidelines useful.

File formats: PNG recommended

JPG format is fine for photographs because of their smooth shading, but it makes line drawings fuzzy. GIF is the traditional format for line drawings, but it has recently been replaced by PNG. PNG doesn't use a proprietary algorithm, and it's actually more efficient than GIF.

Drawing tools

There are several Wikipedia tutorials that show how to prepare graphics. So far, we've successfully used the GIMP for painting and Inkscape for drawing.

UML diagrams

Those tools are fine at general purpose diagramming, but we've found UMLet is a great tool for editing UML diagrams. It stores the diagrams as very simple XML files that just track the boxes and arrows on the diagram. The details of the objects on the diagram are edited using a simple markup language a lot like wiki markup. To edit the diagram, you drag the boxes and arrows around the diagram window using the mouse and type the details in a text window.

UMLet example

This simple class diagram is stored as the following XML:

<?xml version="1.0" encoding="UTF-8"?><umlet_diagram>
<element><type>com.umlet.element.base.Class</type><coordinates><x>30</x><y>130</y><w>140</w><h>60</h></coordinates>
<panel_attributes>Cart
--
+Horse <<property>></panel_attributes><additional_attributes></additional_attributes></element>
<element><type>com.umlet.element.base.Class</type><coordinates><x>10</x><y>10</y><w>180</w><h>70</h></coordinates>
<panel_attributes>/IMoveable/
--
+WheelCount <<property>>
</panel_attributes><additional_attributes></additional_attributes></element>
<element><type>com.umlet.element.base.Relation</type><coordinates><x>80</x><y>60</y><w>40</w><h>90</h></coordinates>
<panel_attributes>lt=<<.</panel_attributes><additional_attributes>20;20;20;70</additional_attributes></element>
</umlet_diagram>

Note the two panel_attributes elements:

Cart
--
+Horse <<property>>

/IMoveable/
--
+WheelCount <<property>>

The double dash puts a horizontal line across the box, and the slashes mean italics. Even the arrows on the diagram are controlled using a markup: "-" means a solid line and "." means a dotted line, and there are codes for all the different arrow heads.

UMLet pros and cons

The good thing is that the diagrams are quick and easy to create. You can compare versions of a diagram to see what's changed using a standard text comparison tool. The downside is that it only saves as JPG and SVG format. JPG looks terrible and SVG needs to be converted to PNG before it can be uploaded.

Inkscape works for converting from SVG to PNG, you can even do it from the command line. Unfortunately, it doesn't seem to know what the current directory is, so you have to use the %CD% variable in DOS.

"\Program Files\Inkscape\inkscape.exe" "%CD%\Sample.svg" -e "%CD%\Sample.png" --export-area-drawing

I think the best way to use UMLet for now is to export as SVG, convert to PNG, upload, and then paste the XML source into the image description page so that others can easily edit it using UMLet.

Future improvements

It would be a lot easier if we could just upload the SVG format or even the original UMLet file to the wiki. Wikipedia currently has an extension that supports this. There's another extension that may also work. If we could get the Wikipedia extension set up to process SVG files, we might be able to use the same technique to process the UMLet file to generate the SVG file. Then we could actually use the wiki history to see changes to the diagram.