How do you share your design decisions with your team?

Developers should learn the design patterns so that they can identify the problem where a particular pattern can be applied to solve the problem elegently. Awareness of patterns helps team members to communicate succinnctly.

My approach is to use diagrams, videos, hand-drawn mock-ups, and iterative refinement is a great way to communicate design patterns and architecture effectively. Let's break down each aspect briefly: Diagrams: Visual representations, such as flowcharts, or entity-relationship diagrams, can convey complex ideas in a clear and concise manner. Videos: Using videos to demonstrate workflows or interactions can be an engaging way to showcase design patterns in action. Hand-drawn Mock-ups: Hand-drawn sketches offer a quick and informal way to brainstorm and explore design possibilities. Iterative Refinement: Recognizing that the initial design may not be perfect is crucial. By seeking feedback from team members and stakeholders.

Design patterns reduce the cognitive load that exists when a engineer is attempting to understand a code base. For example, if there is a package for proxies or a package for strategies regardless of language, frameworks, etc, a glance can help quickly build a mental model of how the code is structured and what is responsible for what. Without this, more energy and time has to be used to build a mental. In addition, design patterns help decompose work and distribute tasks among a team of engineers during design and planning sessions. Their relatively small and concrete nature are a great way to build executable tasks that are easier to think about, unit test and estimate in terms of time.

I prefer perspective wise design diagrams for development and pain area wise design diagrams for improvement. Mock-ups and other architectural artifacts are also great tool to communicate.

I love live documentation, so I favor mainly 2 types of tools: * Wikis, because techs are geek and love everything as code. Nowadays wikies are quite advanced and allow rendering models as well, which helps to keep it easy to update * dashboards: my favorite starting point. I leverage them to design and document everything, including patterns.

Code reviews and pair programming are powerful ways to share design decisions and knowledge within a team, documentation also plays a crucial role in ensuring the longevity and accessibility of that knowledge. Written documentation, such as WIKIs, provides a structured and easily accessible repository of information. It can include design decisions, architectural overviews, coding guidelines, and explanations of key components and modules. This kind of documentation serves as a reference point for team members, especially for those who join the team later or need to revisit certain concepts. Recorded videos with documentation can be particularly helpful for complex topics that may be better conveyed through visual demonstrations.

Here's my approach to effectively sharing design pattern decisions: 1. Comprehensive Documentation 2. Team Discussions 3. Real-life Examples 4. Visual Aids 5. Pair Programming 6. Code Reviews 7. Knowledge-Sharing Sessions 8. Learning Resources 9. Continuous Feedback Loop 10. Documentation in Codebase In summary, effective sharing of design pattern decisions involves clear documentation, open discussions, practical examples, visual aids, collaborative coding, and a commitment to continuous learning. By combining these practices, I strive to ensure that the team is aligned, informed, and empowered to implement design patterns successfully.

Code reviews are a fantastic way to learn and build on the capabilities of a cross-functional feature team. Pull Requests (PRs) enable this by adding the code review step before accepting a contribution to a branch. I highly recommend it. Pair programming might or might not work, depending on individual perception of value. It may even work for some team members and not for others. I recommend experimenting for some time and measure the effectiveness of the approach before adopting it at scale.

Code reviews and pair programming bring both immediate tactical benefits as well as long term strategical benefits. The tactical benefits are that they can reduce faults and errors, or improve performance of the software being worked. The strategic benefits come from building relationships between engineers, helping with creating an environment and culture based on collaboration and trust. This is crucial in all types of teams not just software.

It is very difficult to get a team to a point of being hard to identify who wrote a piece of code. Those variances can be quite big in some scenarios, adding to the maintenance complexity. I would vary from a nice to have, for simple and short lived scenarios, to a must have in large and complex scenarios (possibly multi-team or large volume of contributors). If you are opting in, use it from the start and build it into the CI/CD and PR quality gates. As a thing you bolt on later, it will bring you a world of pain to get everything aligned.

Code should be working as expected and needs to be tested thoroughly. When I see statements like "Code should be readable", I see it as "Code should be poetry". That doesn't add value. We are always running against time. We need to ship it to production. That is how we add value. Using tools to make cosmotic changes? Really? Don't you have better tasks at hand? You have.

I am a serious preacher for shift left quality, from which tests are a part of. Well written tests are a fantastic documentation on how to interact with the solution, and are the best way to onboard contributors, etc. Just enough documentation is always important. How much is a case by case. Enough for all the stakeholders to have enough information to enable them contribute and add value, I would say.

Code and Test are Living Documents. Test Driven Development Help to code from Requirement perspective (Top Down approach). Code should be readable enough that you can minimize waste in terms of external documents.

While workshops and presentations are the way to share your design decisions, it's also important for the team to know why the decision is being made while designing a new feature or modifying the existing design. This makes the people aware of why it is required and based on which they can make proper suggestions and are more involved in the design process.

One thing I've found especially helpful in design presentations is: Is: Risk Mitigation: Identifying and addressing potential risks and drawbacks early on allows the team to proactively manage challenges and minimize the impact of potential issues

Design work sessions, more than workshops, are a useful way to get a common understanding of the problem, possible solutions and dependencies.

I also recommend using Architectural Decision Records (ADR's) where you document architectural decisions so people can later know why code looks the way it does and why it is structured and organized the way it is. This can avoid having the same discussions again.

Effectively sharing design decisions with the team involves comprehensive documentation of choices, scheduling discussions to explain context and rationale, fostering open dialogue, using visuals, addressing concerns, encouraging iterative feedback and reflecting for continuous improvement. This approach ensures clear communication, alignment, and collaboration among team members, leading to successful project outcomes and shared understanding.

To improve design pattern discoverability, consider using generative AI to document and exemplify patterns while safeguarding data privacy. Create templates and code snippets for common practices and aligned starting points. Collaborative tools like "Backstage" foster sharing, discussion, and enhance consistency and efficiency. AI and non-AI approaches can work together to enhance development.