Make Stellar software!
Monoliths, Microservices, Nanoservices, Serverless and now Macroservices – feeling overwhelmed already? I discuss the unhealthy obsession and toxic discussion of one over the other, that we seemingly need to have over and over.
Takeaways: A different approach is exemplified, based on experience.

Go to Make Stellar software!

On Collaboration Artifacts

To achieve success in the development of software, we must communicate effectively about the software. In all technology businesses, there exists a shared language between the business professionals and technology professionals. Sometimes it is verbal and informal, sometimes it is tangible and formalized. In all cases, it is abstract.

What are Collaboration Artifacts?

Collaboration Artifacts are the tangible body of work we create to support our communication and discussion. It is in Collaboration Artifacts that we document knowledge, decisions and research. Collaboration Artifacts will help the organization move towards the desired outcome, whether that is one or more new features, changes to or retiring existing features, or the creation of entirely new systems or services.

Collaboration Artifacts are written documents, illustrations or other items that can be exchanged, viewed and understood by all team members and stakeholders. They are created and maintained in parallel with the production of the software.

Collaboration Artifacts come in many forms, from a simple one-liner on a Trello card or paper napkin, to Mock-ups, flow diagrams and Sequence diagrams.

Collaboration Artifacts are not always part of the final software product, although they may be.

Example Collaboration Artifacts

Start early

The earlier the discussion, modeling and design activities are started and made tangible in Collaboration Artifacts, the better. If the desired changes are of any decent size, it serves no one to rely only on verbal and undocumented exchanges. Instead, by capturing the discussions and decisions in diagrams following an agreed upon standard, delivering the right outcome at the right time will be much easier.

It is a spectrum

Modeling and designing with Collaboration Artifacts often has to be an active choice. Often, we postpone it a little too long, which leads to confusion.

This is not an effort to promote unnecessary ceremony. Consider it a spectrum. Is it a small task? Then a couple of lines might be enough. Is it a relatively large task? Maybe you should add a couple of diagrams and a mock-up. Significant change? You may need to create a larger body of work, that can serve as a lighthouse for your efforts over a prolonged period of time.


Looking to formalize your communication, add quality to your discussions and capture your decisions? Below, I have made a collection of articles on Unified Modeling Language, a very well established standard for modeling software.

My point here is not to convince you to start using UML completely. It is to inspire thinking around what can be done and how easy it is. Also, it is perfectly valid to cherry-pick from UML what works for you, and to discard what does not.

Use case diagrams
Read about an exchange I had on UML diagrams, Use case diagrams in particular, and how they relate to User Stories.
Takeaways: Learn about the benefits of using Use case diagrams and see how roles, actions and systems can easily be visualized

Go to UML Use Case diagrams

Class and object diagrams
Here, I exemplify the benefits of Class and Object diagrams in my efforts to turn a hater into a believer.
Takeaways: Learn how to visualize objects and data in your domain.

Go to UML Class and Object diagrams

Sequence diagrams
Based on a yet another true story I exemplify how a long-lived and potentially expensive assumption was uncovered.
Takeaways: The strength of using Sequence diagrams to document the timing of actions and events in your software.

Go to UML Sequence diagrams