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

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

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

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.

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.

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.


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!

This topic: Projects/MBW/MBW_d > MbwAdmin > MbwIntro
Topic revision: 06 Sep 2008, RichMorin
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