Graph Magic Introduction


Graph Magic (GM) provides both an organizational approach and some handy support software for documenting complex systems in TWiki. Because a "model" of the system is used to structure the documentation, construction and use (eg, navigation) of the documentation are based on (and help to clarify) the system's architecture.

Basic Concepts

GM is based on four concepts from graph theory and Object-Role Modeling: nodes, edges, roles, and views. The generality and simplicity of these concepts make it (relatively) easy to model the structure of a very wide variety of systems. Once the structure has been modeled, detailed information can be added to appropriate pages.

  • A node represents a part of the system being documented. This might be a computer, database, file, program, etc.

  • An edge represents a relationship between (sets of) nodes. This might be an API, a network connection, etc.

  • Each edge has two or more active roles, filled by specified nodes. Typically, the first two roles are the edge's "source" and "target" (eg, the sender and receiver of a message). Complex relationships may require more roles, however, so GM allows up to five roles per edge.

  • A view presents a topical subset of the available nodes and edges (ie, a subgraph). The topic might be a shared activity (eg, system restart), a common attribute (geographic location), etc.

Although GM demands that TWiki pages be constructed in a specific manner and contain specific information, GM makes it easy to create such pages. Then, because the information is available in a machine-friendly format, it can provide user-friendly diagrams, indexes, links, etc.

GM's cross-linking and indexing facilities allow documentors to create richly-linked sets of pages whose overall structure correspond closely to that of the system being documented. They also encourage the "Don't Repeat Yourself" (DRY) approach: because content (eg, Precis, Summary, Title) from each page can be easily viewed on other pages, it doesn't need to be repeated there.

Modeling A Spreadsheet?

GM could, conceivably, be used to model (ie, document) a spreadsheet...

A1_B2.png    Spreadsheet cells are named by their row and column (ie, column A contains cells A1 and A2). Being able to manipulate rows, columns, and rectangular areas adds great power to the spreadsheet metaphor.

Restating this in GM's nomenclature, View A displays Nodes A1 and A2, along with any Edges they have in common. Views 1, 2, and B behave similarly.

However, GM's views are not limited to rows and columns. So, a view can be based on any desired set of common traits, relationships, etc.


GM is based on TWiki, which is based on the Web. So, most features in GM should seem pretty familiar. Expect to find lots of links (with tooltips, where appropriate). TWiki already makes it easy to generate rich sets of links; GM simply adds its own (autogenerated) links to the picture.

GM makes quite a bit of use of disclosure controls, in an effort to keep things tidy. So, look for "More..." links, disclosure triangles, etc. You should also expect icons (eg, in Context Diagrams on View pages) to be clickable and have tooltips.

If you see a page that could use more content, and the Prevailing Authorities allow this, jump in and add the content. Adding new pages is a bit trickier, but the pages described below should make this relatively painless. However, it's always a good idea to understand the GM setup before fiddling with form checkboxes, let alone adding new Edges, Nodes, and/or Views.


Identify the nodes (eg, components) and views (eg, activities) of interest. Avoid the temptation to dive down into detail at this point; that comes later. For each view, sketch up a simple diagram (eg, using circles for nodes and arrows for edges). If you can't easily create such a diagram for a view, you may need to sub-divide the view, reconsider the level of abstraction, etc.

Create some node and view pages. Play with the TWiki forms, to get an idea of how they work, where and how their information appears, etc. When you have all of the nodes needed for a view, try filling in the edges. Rinse, repeat...


Most web and wiki users are quite content to ignore the mathematical basis for web pages, links, etc. However, by paying explicit attention to the underpinnings, we can add general and powerful functionality. Graph Magic (GM) is a simple exercise in this direction.

Like the rest of the World Wide Web, TWiki is structured as a directed graph. Pages are "nodes", links are "edges", etc. By clicking a link, the user traverses an edge between two nodes.

By adding other structure (eg, "parent" links, "webs"), TWiki makes it possible to view pages in terms of nested hierarchies. Finally, it provides "brute force" searching capabilities which allow a page to locate all other pages whose content matches specified patterns (eg, regular expressions).


GM is basically just an approach to using TWiki. Borrowing from graph theory, it provides a framework for dealing with nodes and edges. To ease comprehension and navigation, it adds the notion of "views".

GM is intended for use in documenting systems of interacting components. Each component gets a node page (via NodeCreate). Each interaction path gets an edge page (via EdgeCreate). Finally, collections of nodes and edges are pulled together into views (via ViewCreate). Each view documents the way that its nodes and edges are used to perform a given activity, etc.


The pages discussed below are intended to be used, examined, and modified. However, be cautious about modifying pages in a production GM web, lest you break things you can't fix!

... Create

The Edge, Node, and View Create pages are used to create GM pages. They perform all sorts of convenient, critical, and tricky functions; please use them!

... Form

The Edge, Node, and View Form pages define the TWiki "forms" that are used (respectively) by actual edge, node, and view pages. They define the names and characteristics of fields, form appearance and interaction, etc.

... Index

The Edge, Node, and View Index pages are simply indexes to their respective page types.

... Names

The Node and View Names pages are used by TWiki's "form" infrastructure. Each of these pages contains a single-column table which lists the members of a given page type (eg, Node, View). The order of the items in the table controls the order of presentation in the forms and other locations.

Note: Several "wrapper" pages (eg, NodeName, NodeOmits, Role1, ViewName) are used to keep the names of form fields tidy. These pages simply INCLUDE content from the NodeNames or ViewNames page.

... Template

The Edge, Node, and View Template pages are used in the page creation process. If you have some boilerplate text, a header, or a reminder to include some item, put it in the appropriate template page and it will appear in each created page.

Gm Includes

Most of the "magic" in GM resides in GmIncludes and subsidiary (eg, GmIncludesAB, GmIncludesAW) pages. We have attempted to include useful documentation, but some parts may still be mysterious. Feel free to inquire...


The GmYAML page won't be of direct interest to most users, but it's a very important part of GM. This page generates a machine-readable description of the graph. External programs can then use this information to create diagrams, etc.

This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r6 - 18 Aug 2008, RichMorin

Available Webs

This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email