Trimble Patterns and Practices - System Design

Welcome

This site provides examples and resources for Systems Architects to consistently document, evaluate, invalidate and improve their system design ideas in an open, collaborative environment.

You read that right: Invalidate. Because you can never actually validate or prove a theory. You can only put it through multiple rounds of invalidation until you feel reasonably confident in the theory’s usefulness. Design diagrams and service descriptions are exactly that: theories about a potential design. Such theories get stronger under scrutiny, criticism and adjustment to accommodate new information.

Inconsistent System Design Documentation

Software design documents often get stuck behind a litany of different tools and constant licensing issues. One individual or team uses one set of tools, and another uses a completely different set. Remembering where documents and designs are stored, then finding and accessing them at the right time can be a significant challenge for individuals, much less for groups and teams.

Concepts also frequently get lost in translation. It seems like each architectural diagram can present a new and unique language to learn. Even the creator of the diagram can’t remember what the symbols and lines are supposed to mean! It’s enough sometimes to make you want to surrender.

Consistent System Design Documentation

This site demonstrates how simple tools can be used to generate system design documentation that is searchable, consistent, extensible, and can live very close to, if not right next to the code it describes. No more hunting through Confluence, Miro, LucidChart, Draw.io, Google Drawings, (the list goes on!), and the like.

The Notification Call Chain diagram provides an example. Clicking on the image of the diagram zooms in for a closer look. The diagram also includes a “View Source” link right below it. Clicking on that link reveals the text that is used to render the diagram. The source of these diagrams can easily be posted into VS Code where lots of wonderful extensions exist for PlantUML, Graphviz, and mermaid.js. There are great online playgrounds as well for taking these tools out for a test drive.

Once you get the hang of text-based diagramming, you won’t want to go back. Once system design documentation becomes subject to the same rigorous review process as the software itself, consistency begins to emerge, communication improves, and productive collaboration accelerates.

Getting Started

Start with the curated list of books. In particular, you’ll need copies of Righting Software and Thinking in Systems to guide you on your journey.

Righting Software describes techniques for System Design and Project Design that software architects can use to guide their design process.

Thinking in Systems provides a great introduction to general systems thinking that can be applied broadly, as well as to software system design.

You can also download a copy of the Righting Software Book Club Guide as an additional resource to use as you are learning the techniques of System Design.

Contribute!

The more systems and patterns we can model in a consistent paradigm with common techniques the better!

Pull requests are a welcome opportunity to invite others to evaluate, improve and yes, invalidate your design ideas!

Get involved with the project on GitHub