Model-based documentation (MBD) is based on the idea that a "model" of the system under study should be used to structure the system's documentation. So, construction and use (eg, navigation) of the documentation are based on (and help to clarify) the system's architecture. Many mechanized documentation systems (eg, documentation generators such as Doxygen) follow this approach. However, creating a mechanized documentation system is not a trivial exercise; certainly, it requires substantial programming effort. On the other hand, millions of users already know how to use and edit wikis. Given a well-defined approach and a set of support tools, these users should be able to create Model-based Wikis (MBWs) on any desired subject. The platform chosen (TWiki) already has provisions for handling forms, metadata, scriptable searching, etc. Using these features, the support tools collect metadata from the user, augment wiki pages with links and precis information, and even generate clickable "context" diagrams.This web (MBW) applies a Model-based Wiki (MBW) to the problem of documenting its own infrastructure (recursion: see recursion).-- MBW Introduction
Basic ConceptsMBW is based on four simple concepts: nodes (eg, components), edges (eg, interactions), roles, and views (eg, activities).
- 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.
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. 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.
- 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.
These indexes are very useful if (a) the MBW isn't too big and (b) you're able to recognize what you're looking for. The View Index is usually the best starting point.
This is a typical Node page. Click on the links in the "Context and Navigation" section to get an idea of their capabilities. Note that the icons in the context diagram have tooltips and can be clicked to get to the page in question.