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.
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...
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.
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
is structured as a
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!
are used to create GM pages.
They perform all sorts of convenient, critical, and tricky functions;
please use them!
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.
are simply indexes to their respective page types.
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.
Several "wrapper" pages
are used to keep the names of form fields tidy.
These pages simply INCLUDE content
from the NodeNames
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.
Most of the "magic" in GM resides in GmIncludes
and subsidiary (eg, GmIncludesAB
We have attempted to include useful documentation,
but some parts may still be mysterious.
Feel free to inquire...
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!