8.2 Treaty Considerations

The Starbucks example illustrates the two main considerations of treaty design:

1. Workflow. How does work flow from one fortress to another?

2. Error management. How does one fortress report an error to another fortress?

You might expect security to be part of the treaty. In the Starbucks/Roger collaboration, I had to hand over my American Express card to prove I was authorized to make a charge on that particular account. It is reasonable to think of security as part of the treaty, but I think of it as a feature of the drawbridge rather than of the treaty, and I recommend documenting the drawbridge in the fortress documentation. Either approach is fine, though.

Treaties are spelled out in treaty overview documents (TODs), as I discussed in Chapter 2 (Diagramming Software Fortresses ). The exact format of a TOD can be defined on an institutional basis because, at least for now, TODs are used by human beings, not software systems. If we ever reach the point where TODs become data digested by software infrastructures , we will need to develop standard representations of TODs. That day is still in the future. For the moment, we will be more than satisfied if we can come up with a technique that allows people to communicate with other people. For human beings, the most important information in the TOD is probably the collection of SADs.

The difficult part of documenting a treaty is knowing how much detail to include. A good test is reimplementability: If any party of the treaty were to be reimplemented from scratch, the treaty, in conjunction with the fortress documentation, must contain sufficient detail for the reimplementors to understand how to fulfill their responsibilities with respect to the other fortresses in the treaty.

It's hard to give much more guidance than this. Treaties tend to be very specific to the work being coordinated. I hope this gives you some ideas on how to proceed.