As I have worked to coach teams on improved communication, I have started to reflect upon the value of classic software engineering artifacts and diagramming techniques. I love the benefits of visual communication. On this blog, we tend to focus on ways teams can implement agility into their flow. Many agile teams can forget the benefits that traditional UML(unified modeling language) brings. The agile manifesto challenges us to avoid comprehensive documentation. Hopefully, we’ll highlight some of the high value elements of UML.
As engineers, we can often become too focused on our implementation tools like languages and code editors. I feel it’s important for teams to decide on a few document types that guide their decisions around project scope and component responsibility. You should consider reaching for a classic visual diagramming pattern when you feel it facilitates a communication challenge with your team. At key moments, we want our teams to see the big picture. In the post, I will submit that these diagrams help your teams plan, scope and communicate more effectively.
In this post, I will advocate for the benefits and core concepts of a few high value document types. You can decide to find references on UML using Google. You may find it tedious to honor every exact detail that UML encourages from visual communication. Personally, I don’t find value in following UML diagramming style to the letter of the law. I leverage the visual diagramming concepts that help my team create a trusted design. We leverage the UML rules opportunistically.
Use case models
Use case diagrams provide a clear and concise visual representation of the system’s functionality, fostering better communication and understanding among stakeholders with varying technical backgrounds. Everyone, from developers to clients, can grasp the system’s interactions and functionalities at a glance.
[1]
Here are a few guidelines to follow when creating a use case model with your team.
– Actors: Decide on the key actors in your system. You need to think beyond a generic user. What can the administrator do? What can managers do? What can customers do? What does the system do autonomously?
– Define Boundaries: Make a big box(boundary box) to represent the major elements of your system. (web portal, mobile device, server)
– Features: For each “big rock” feature of the system, make a box. Place the feature box inside one of your boundary boxes.
Use lines, dots or colors to document actors that own each feature box.
– Define externals: Engineering stakeholders should place external storage or API integration points outside the system boundary.
– Connect to externals: Engineering stakeholders should use lines, dots, or colors to document required integration with a database or API integration point.
In my experience with innovation projects, I feel that this diagram helps our team members know clearly the target audience of our innovation and a draft project scope. This flavor of conversation becomes critical to customer, product and engineering alignment and shared vision. You can often draft user stories or epics directly from this diagram. For each connection between an actor and a feature box, the design team probably needs to draft a visual design. When a feature box touches an external, the team can probably write some kind of integration user story.
With this one page document, it has been helpful for engineering to quickly identify use cases that have high schedule risk. Engineering has the opportunity to recommend “big rock” use cases critical to the vision of the product.
This kind of diagram often generates longer term questions that you probably can’t answer today. At the start of a project, you have a limited amount of perspective. A leader once coached me to write down those questions as spikes or research tasks on the product backlog.
In future blog posts, we’ll comment upon some other document types that help guide the team design process effectively.
Do you have any favorite agile documentation types to help your team to align?
References:
[1] https://en.wikipedia.org/wiki/Use_case_diagram
Leave a Reply