What is the best way to document a system metaphor?

Question

A metaphor help us to communicate with our project stakeholders, using a shared set of concepts and analogies. we develop them all the time, in one way or another. even the XP- programming highly recommend to get it defined since project start.

How do you write such thing down in a document (specially if it already exists)? maybe a dictionary-like approach?

UPDATE: perhaps a thesaurus would do it better (synonyms sum).

Answer 1

A dictionary is a great format the shared terminology. Hyperlinks should cross-reference in case they're looking at a soft copy. For the analogies: keep them short, at first.

Such a document is probably the most important page of text in the whole project::

• The dev team needs to speak this language. Designing the DB and your object model are about 200% easier if you're using and thinking in the right terms.
• Your customers reviewing it always brings to light some false assumptions on the your part. Finding these early is gold.