Where to Put the Ever-Evolving Design Artifacts

The most important things about a design artifact are,

1.     It can easily be changed.

2.     It preserves change history – so that one can “undo” mistakes, and go back to revisit earlier ideas.

3.     It is easily understood; which implies simplicity in each view.

4.     It is available to all and can be edited by all, and easy to find what one is looking for.

Hierarchy is important – use a hierarchical wiki.

Content should be embedded directly in the repository pages – not as uploaded documents that need to be independently opened.

Diagramming is absolutely essential, and editable directly in pages – not as separate images that are created elsewhere and uploaded.

Diagrams should be simple and easily understood, and not require special tools or use arcane symbols when simpler symbology with textual annotations would suffice – hence “Simple Modeling Language” (discussed later).

Design views should include all the elements needed to explain a design decision. Thus, they should not be arbitrarily limited to “interactions” or “classes” and so on. IME, one usually needs to include some classes, some instances, some sequences, and some interactions in a single diagram in order to illustrate how something should work.

Keep design up to date – part of DOD. (See “The Definition of Ready, and Definition of Done”, later.)