Automating Diagrams with Visio

Written by: Michael Angeles

We have all heard the adage, “Good, Fast, Cheap: Pick any two (you can’t have all three).” The saying might generally be true of the work we produce as designers of information-use environments. Try to test the saying against one of the deliverables we might create—a high-fidelity interface prototype, for example—and see if you can disprove it. You can produce beautiful prototypes in Illustrator, but it will cost you time and money. You can do rough prototypes quickly and cheaply by hand, but the end result won’t look as polished as the Illustrator version.

Turnaround time can be relatively quick if you push your tools to perform for you. Site maps and user flow diagrams are good candidates for automation.

My approach to producing deliverables is to falsify the truism. I do the demanding intellectual work first and then force the tools to succumb to my need to produce seemingly speedy deliverables. The illusion of speed happens because you do the hard work up front—planning, analyzing and documenting your work in doing content inventories, designing user flow, etc. When it is time to realize that work in a document, the turnaround time can be relatively quick if you push your tools to perform for you. In this article I illustrate one method for producing diagrams quickly using software.

The process overview

We probably do most of our intellectual work in preparing deliverables before ever touching a drawing program. When the elements of the information architecture and user experience are defined, we are often expected to produce a polished document to visually represent the information. We can take a semi-automated approach to produce some of these documents using software. Site maps and user flow diagrams are good candidates.

The process I propose assumes that you’ve spent grueling hours doing the work of preparing your content inventory or sketching your user flow diagrams and now want to render your boxes and arrows for presentation. The next step in the process is to take the data produced in that intellectual work and prepare it for use in a diagramming application.

I will illustrate a process that relies on text files exported from Excel and uses Visio to transform those text files into diagrams. You can also use a database management system for this process, but details about using a DBMS are out of the scope of this article.

The steps to be covered in this process

  • Identify and document your nodes
    • For site maps, identify nodes in a content inventory, hierarchically arranged
    • For flowcharts, sketch and identify shapes and connectors
  • Document nodal connections
    • Indicate how parent nodes explicitly link to child nodes
  • Prepare text file for importing to a drawing program
    • Prepare a “shapes” file in Excel or with a text editor
    • Prepare a “links” file in Excel or with a text editor
      • If using Excel, export files to comma- or tab-separated file (saved as .csv or .txt)
    • Combine shapes and links files into one text file for importing into Visio
  • Open/Import and auto-diagram
    • Open the text file in Visio
  • Modify the diagram
    • Manipulate the diagram shapes for clarity and apply any cosmetic changes

Creating site maps or content architecture diagrams

We spend a good deal of time working with content to produce documents that help clarify the scope of data contained in websites. Key to the work of information architecture is the production of documents that list the site contents hierarchically (content audits or inventories) or diagrams that depict the site structure visually (site maps). The content inventory is the starting point in defining our information architecture. Graphic designers and technical people often use these documents in system and design specifications.

Step 1: Identify and document nodes in a content inventory

The process of specifying new data or auditing existing data to be included in a site helps to clarify the next steps in organizing that data for presentation. The inventory of data is often used to produce taxonomies or categories of access points. These access points usually inform the navigation and interface design.

Inventoried content is often categorized as a hierarchy of nodes (categories and subcategories, branches and leaves). A high-level extraction of the top-level nodes, perhaps even several levels deep, might give a good idea of the site structure.

To illustrate how to prepare your text files, consider this portion of a hierarchy for a hypothetical company website.

Content hierarchy for boxywidgets site

  • 1.0 Home
  • 2.0 Corporate information
    • 2.1 What we do
    • 2.2 Who we are
  • 3.0 Our process
    • 3.1 Discovery
    • 3.2 Concept
    • 3.3 Creation
    • 3.4 Implementation
    • 3.5 Rollout
    • 3.6 Testing
  • 4.0 Our clients
    • 4.1 Case studies
      • 4.1.1 Web
      • 4.1.2 CD-ROM and kiosks
      • 4.1.3 Print
    • 4.2 Client list
  • 5.0 Contact information
    • 5.1 Locations
    • 5.2 Online inquiry form
      • 5.2.1 Inquiry form submitted
      • 5.2.2 Inquiry form error

This example shows all the available nodes in a small site. All that Visio will need is a listing of the nodes that we want to diagram.
This list is comprised of:

  1. “Shape Name”—a unique numerical idea for each node and
  2. “Shape Text”—a label for the node. If this data is coming from a more complete content audit document, you should extract only the id and label for this exercise. This is fairly simple to do in Excel if you copy the data to a new sheet and remove the unwanted columns.

Visio accepts a number of other values in the file you import. They are as follows:

Shape,”Shape Name”,”Master Name”,”Shape Text”,”ShapeX”,”ShapeY”,”Width”,”Height”,”Property”

For our task, we are interested in the “Shape Name” and “Shape Text” values. We can simply skip all of the fields following “Shape Text”, but must include blank values using empty quotes (“”) for any fields that we are skipping before the last field. In this case, we use empty quotes for “Master Name” because we’re only using boxes in this diagram. The first value in each line is always the word “Shape” to indicate to Visio that this is the definition for a shape it will draw.

If you are authoring these files in Excel, you can create the first column for the “Shape” value and auto-fill all of your rows with the value “Shape”. The second column will hold your “Shape Name” values. The third column will be a placeholder for the empty “Master Name” field. The fourth column will hold your “Shape Text” labels.

Our sample Excel file would look like this:

Excel sheet with stripped down content inventory

Excel sheet with stripped down content inventory

We can export this sheet to a text file of comma-separated values (saved as .csv) and the resulting file for the content hierarchy will look like this:


; shapes.csv
; Shape file for Boxy Widgets site
Shape,"1.0","","Home"
Shape,"2.0","","Corporate information"
Shape,"2.1","","What we do"
Shape,"2.2","","Who we are"
Shape,"3.0","","Our process"
Shape,"3.1","","Discovery"
Shape,"3.2","","Concept"
Shape,"3.3","","Creative"
Shape,"3.4","","Implementation"
Shape,"3.5","","Rollout"
Shape,"3.6","","Testing"
Shape,"4.0","","Our clients"
Shape,"4.1","","Case studies"
Shape,"4.1.1","","Web"
Shape,"4.1.2","","CD-ROM and kiosks"
Shape,"4.1.3","","Print"
Shape,"4.2","","Client list"
Shape,"5.0","","Contact information"
Shape,"5.1","","Locations"
Shape,"5.2","","Online inquiry form"
Shape,"5.2.1","","Inquiry form submitted"
Shape,"5.2.2","","Inquiry form error"

Any line that is preceded by a semicolon (;) is ignored as a comment. I added comments in the first two lines to indicate what this file is used for. The next file we want to create is the file that shows relationships between nodes.

Step 2: Document nodal connections

The list we created above is a hierarchical listing of nodes, so the numbers and position in the list already indicate relationships. However, Visio requires that we explicitly reiterate the relationships by indicating child-parent connections following the format below.

Link,”Link Name”,”Master Name”,”Link Text”,”From Shape (or Connector) Name”,”To Shape (or Connector) Name”

We only need the “From Shape” and “To Shape” values for this file. The first value in each line is always the word “Link” to indicate to Visio that this is how the shape identified in the “From Shape” field will link to a shape in the “To Shape” field. Our link file for the example above would look like this.


; links.csv
; Link file for Boxy Widgets site
Link,"","","","1.0","2.0" ; Link the "Home" to "Corporate information"
Link,"","","","1.0","3.0"
Link,"","","","1.0","4.0"
Link,"","","","1.0","5.0"
Link,"","","","2.0","2.1" ; Link "Corporate information" to child "What we do"
Link,"","","","2.0","2.2"
Link,"","","","3.0","3.1"
Link,"","","","3.0","3.2"
Link,"","","","3.0","3.3"
Link,"","","","3.0","3.4"
Link,"","","","3.0","3.5"
Link,"","","","3.0","3.6"
Link,"","","","4.0","4.1"
Link,"","","","4.1","4.1.1"
Link,"","","","4.1","4.1.2"
Link,"","","","4.1","4.1.3"
Link,"","","","4.0","4.2"
Link,"","","","5.0","5.1"
Link,"","","","5.0","5.2"
Link,"","","","5.2","5.2.1"
Link,"","","","5.2","5.2.2"

Step 3: Diagram in Visio

We now take the two text files created above and merge them into one file that we are going to save as “ex1_visio_import.csv”. Now we are ready to open the file in Visio using the steps below.

  • File > Open (open dialog window appears)
    • Files of type: Text Files (*.txt,*.csv)
    • Select file “ex1_visio_import.csv”
    • Click Open (File Converter dialog window appears)
  • Visio File Converter dialog window
    • Field Separator: ,
    • Text delimiter: ""
    • Comment character: ;
    • Click OK

The end result is a diagram that needs a good deal of clean up. You can move the boxes around and play with colors to produce a more readable diagram.

Automatically generated site map (click to enlarge)

Cleaned up site map (click to enlarge)

 

Of course if you don’t want to see your diagram in the hideous colors that Visio gives you to work with, you can copy the diagram and paste into Illustrator where you can make it more presentable and pleasant to look at.

Creating user flow diagrams

While I think it’s rather nifty to create site maps using Visio, I have to admit that what I really prefer to create in Visio are flowcharts.

Flowcharts can be used to help the team understand how users might interact with your system. Interactions such as registration or e-commerce transactions may best be planned using flowcharts. They are also used in diagramming system logic for applications. These documents are often developed with technical people and serve to assist technical staff and graphic designers.

The process for doing flowcharts in Visio is the same as the process shown above for site maps, except we will also be introducing values to specify which shapes to use. We also have to tell Visio which stencils to get the shapes from by specifying a template. With flowcharts, there is less need to move your shapes around once you’ve imported them into Visio. I hardly ever touch the colors and fonts. I view flowcharts as utilitarian documents that are meant to illustrate system logic, so I prefer to show them in grayscale and prefer the linear top-to-bottom presentation, connecting pages with connector symbols when necessary.

To get you started I will illustrate how to use the process shown above to diagram a very simple flowchart. Since you are now familiar with the file preparation, I’m just going to define the fields that can be included for the node and link sections and then show you the files combined in one import file.

Step 1: Document nodes in flowchart

Flowcharting does not lend itself to listing shapes in a hierarchical list the way site maps do. The best approach is probably to first draw your flowchart on paper and number the shapes in the chart. You can then take each numbered shape and add it to your text file. All that Visio really needs to create your flowchart are a few required fields:

  1. The “Shape Name”—the unique numerical id you give it
  2. The “Shape Master”—the name of the shape you want to use from the Visio template (Terminator, Processing, Decision, etc.), and
  3. the “Shape Text”—the label for the shape.

Visio will also accept a number of other values in the file you import. The order of fields should appear as follows:

Shape,”Shape Name”,”Master Name”,”Shape Text”,”ShapeX”,”ShapeY”,”Width”,”Height”

The first value in each line is always the word “Shape” to indicate to Visio that this is the definition for a shape it will draw. We can simply leave off all the values following Shape Text, but we must include blank values using empty quotes (“”) for any values that we are skipping before the last value. If we don’t want to specify shape size and position, we can just skip the last four fields. I’m going to do that for this example.

Step 2: Document nodal connections

Since you have a sketch of your flowchart it should be fairly easy for you to create a list of the links between shapes.
Visio will expect at the very least that you include:

  1. “Master Name”, the name of the connector you will use
  2. “From Shape (or Connector) Name”, the numerical idea or “Shape Name” from the shape list, 2) “To Shape (or Connector) Name”.

The first value in each line is always the word “Link” to indicate to Visio that this is how the shape identified in the “From Shape” value will link to a shape in the “To Shape” value. There are some additional fields that you can use including “Link Text”, a field for a text value that can appear over the connector lines. For our example, we’re going to skip the extra fields and indicate them with empty quotes. The order of fields should appear as follows:

Link,”Link Name”,”Master Name”,”Link Text”,”From Shape (or Connector) Name”,”To Shape (or Connector) Name”

Step 3: Diagram in Visio

Now that we know what shapes to include and how to link them, let’s look at the combined import file we would create for this simple example. We need to indicate to Visio the stencil to reference when looking for shapes identified in our “Master Name” field. So begin the first line with the keyword “Template”, followed by a comma and the name of the Visio stencil file. Stencil templates are the Visio files followed by the extension .vst. You can get the names of stencil templates and stencil files by browsing in your Visio Solutions folder (usually located in “C:Program filesVisioSolutionsFlowchart”) In this example we’ll use the flowchart template “Audit Diagram.vst”, which includes the “Audit” and the “Connectors and Callouts” stencils.

Here is the import file for our example:


; ex2_visio_import.csv
Template, "Audit Diagram.vst"

Shape,"1","Terminator","Start",,,,,,,
Shape,"2","I/O","Some kind of input",,,,,,,
Shape,"3","Decision","Test the input",,,,,,,
Shape,"4","Display","Display true message",,,,,,,
Shape,"5","Display","Display false message",,,,,,,

Link,,"Next",,"1","2"
Link,,"Next",,"2","3"
Link,,"Result",,"3","4"
Link,,"No result",,"3","5"

We can save this file and open in Visio using the following steps:

  • File > Open (open dialog window appears)
    • Files of type: Text Files (*.txt,*.csv)
    • Select file “ex2_visio_import.csv”
    • Click Open (File Converter dialog window appears)
  • Visio File Converter dialog window
    • Field Separator: ,
    • Text delimiter: “”
    • Comment character: ;
    • Click OK
Automatically generated flowchartAutomatically generated flowchart

Summary

That’s all there is to it. You now have a simple process for generating diagrams in Visio from text files. It won’t make the intellectual work of preparing content inventories or user flow specifications much easier, but it may buy you some time when it comes to rendering that information in a drawing application.

If you work in an organization where you are expected to make modifications to your deliverables quickly, you might value this process. This process will help you make modifications a bit more quickly to those specifications you’ve spent hard hours on, so you can impress your colleagues and clients with how efficient you are.

For more information


Michael Angeles is an information specialist and site developer at Lucent Technologies, Bell Laboratories in the Information Solutions department. He maintains a weblog of information architecture news at http://www.iaslash.org.