MBW Introduction

Theory

Model-based Wiki (MBW) 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

MBW 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 MBW 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 MBW demands that TWiki pages be constructed in a specific manner
and contain specific information, MBW 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.

MBW'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?

MBW 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 MBW'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, MBW's views are not limited to rows and columns.
So, a view can be based on any desired set
of common traits, relationships, etc.

Use

MBW is based on Wiki (in this implementation, TWiki),
which is based on the Web.
So, most features in MBW 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;
MBW simply adds its own (autogenerated) links to the picture.

MBW 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 MBW setup
before fiddling with form checkboxes,
let alone adding new Edges, Nodes, and/or Views.

Creation

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...

Background

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.
MBW 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.

Details

MBW 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".

MBW 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.

Pages

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

... Create

The Edge, Node,
and View Create pages
are used to create MBW 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.

... 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.

MBW Includes

Most of the magic in MBW resides in MBW Includes
and subsidiary (eg, MBW Includes AB,
MBW Includes AW) pages.
We have attempted to include useful documentation,
but some parts may still be mysterious.
Feel free to inquire...

MBW YAML

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