CFCL GraphMagic

This project is mostly a testbed for some documentation ideas. We've used local system administration info as the data.

For actual System Admin notes on CFCL, however, see the CFCL web.

Getting Started

The Graph Magic Introduction page offers a concise, if somewhat chewy, introduction to the way that this TWiki web is constructed. In case you're not ready to tackle that page, however, here's a precis:

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.

Activities


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: r37 - 08 Sep 2016, VickiBrown
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback