0:03 How often did you find yourself in the
0:06 annoying situation of steering the wheel
0:09 towards a completely different direction
0:12 for delivering a new feature due to lack
0:15 of clarity of what to express inside
0:17 your code? Fear not because this video
0:20 is going to provide you the answers to
0:22 all those questions. I want to share
0:25 with you stories from the trenches,
0:27 techniques and mechanism for finally
0:29 cracking the code and getting enough
0:31 documentation to succeed in your
0:34 software project. Are you ready? Let's
0:36 dive in. [Music]
0:41 [Music]
0:44 Hi everyone, my name is Luca. I'm an
0:46 architect super passionate about
0:48 software architecture and the
0:50 intricacies of its social technical
0:54 aspect. I spent over 20 years of my
0:56 career working from embedded or low-end
0:58 devices to global distributed system in
1:00 the cloud and now I'm principal
1:02 serverless specialist in AWS. Where are
1:05 we? Oh yes, documentation. Documentation
1:08 plays a critical role in the software
1:10 development process especially in
1:12 distributed system such as
1:15 microservices, microrends, data mesh,
1:17 documenting software architectures helps
1:20 to align teams, scale businesses and
1:22 empower developers. Many people think
1:25 architecture is just a technical topic.
1:27 It's definitely not just a technical
1:30 topic. Keep in mind that a lean mindset
1:32 is essential here. We need to have
1:34 enough design up front to start our
1:36 development process and we should
1:39 maintain our diagrams to democratize the
1:42 evolution of a system across every
1:44 function of your tech department. Too
1:47 often I have experienced teams not fully
1:48 understanding what they have to build.
1:51 rushing to create the proof of concept
1:53 that nail down the complexity of a
1:56 technical part only halfway through the
1:59 process realizing that they forgot a key
2:01 detail that now requires a greater
2:04 effort than designing the project with
2:06 that in mind up front. It's time to
2:09 change our habits and dedicate enough
2:12 time in designing up front enough
2:15 architecture that will allow us to move
2:17 forward our projects. I don't want to
2:19 overwhelm you with thousands of
2:21 techniques but just the ones I have seen
2:23 more successfully applied in many
2:26 organization that have brought benefits
2:28 in the development of software across
2:30 multiple teams. During this video I'm
2:32 going to introduce you to several
2:34 techniques architectural decision
2:36 records request for comments eventtor
2:40 storming and the C4 model. At the end of
2:42 this video, you will have a solid
2:45 understanding of each method and be well
2:47 equipped to start changing the way you
2:49 model and deliver software. Why
2:52 documentation matters? Software modeling
2:54 at the beginning of the project is a
2:57 fundamental step that too often is
2:59 ignored or teams don't dedicate enough
3:01 time to this practice. This will
3:03 accelerate drastically the development
3:06 process because everyone has clarity of
3:08 intentions. That doesn't mean we have to
3:12 nail down every single detail up front,
3:15 but have a just enough architecture to
3:17 start the process. The focus before
3:19 coding should be nailing down the
3:21 architecture characteristics and
3:23 business characteristics. This share
3:26 understanding provides several benefits.
3:27 streaming line decision making,
3:30 simplifying on boarding for a new team,
3:32 facilitating collaboration between cross
3:34 functional teams, reducing potential
3:36 misunderstanding, ensuring consistent
3:38 knowledge transfer. Now there is no
3:40 denying the value of well-curated
3:41 structure and updated software
3:44 documentation. It's a mustave nowadays
3:46 and we cannot forgotten. When everyone
3:48 inside the team understands the
3:50 architecture, they are aligned in their
3:54 vision and objectives. This alignment is
3:56 what allows team to move along the same
3:59 path regardless of their unique roles
4:00 and responsibilities. Essentially, we
4:03 are talking about creating an unified
4:05 perspective that helps all the
4:07 stakeholders including developers,
4:10 project managers, QA and even clients
4:12 maintaining consistent view of the
4:15 architecture. This alignment results in
4:16 more streamline decision-making,
4:19 lowering the chances of costly missteps
4:21 caused by miscommunication or
4:23 misunderstandings. Alongside
4:24 facilitating alignment, software
4:26 documentation promotes the profound
4:30 concept of a synchronous growth. Imagine
4:32 your company decide to scale, attracting
4:35 new hiring or exploring new verticals.
4:37 When new members join the team, how
4:39 would you bring them up to speed with
4:41 the software architecture? This is where
4:43 documentation comes in. Instead of
4:46 relying of individual knowledge transfer
4:47 which can be inconsistent and time
4:50 consuming, well doumented software
4:52 architecture can provide an onboarding
4:55 mechanism that is available 247.
4:58 Furthermore, documentation is not just
5:01 an invaluable resource for the present
5:03 but also an investment for the future.
5:05 As the software evolves, the
5:07 documentation stands as chronicle of the
5:10 project's journey, helping future teams
5:12 understand why certain architectural
5:15 decision were taken. In summary, if you
5:17 want to streamline your internal
5:20 processes, scale effectively and create
5:22 a robust foundation for both the present
5:25 and future growth of your organization,
5:27 you absolutely need to prioritize
5:30 software architecture documentation.
5:32 Before we start, I want to spend a few
5:34 words on another initiative that I
5:36 started a few years ago. It's a
5:38 newsletter. It's called Dear Architects.
5:39 It's a free newsletter where I collect
5:41 weekly the articles I found most
5:44 interesting and that can spark new ideas
5:46 for you and your teams. Every newsletter
5:49 comes with five distinct resources on
5:51 software architecture. The content is a
5:53 collection of great resources found on
5:55 the web that lands in your inbox every
5:58 week. I cover topics like generative AI,
6:01 distributed system, design patterns,
6:03 observability, migration and
6:05 modernization journeys, case studies
6:07 shared by well-known brands in the
6:10 industry and way more. If you are
6:12 interested to know more, click the link
6:14 in the description and register now. No
6:17 advertising, completely free. Join the
6:19 community composed by tens of thousands
6:22 of members already. We'll now dive into
6:24 the details of var documentation
6:27 techniques. Let's start with the ADR or
6:30 architectural decision record is an
6:31 effective approach to documenting
6:34 architectural decisions made during the
6:36 software development process. It was
6:38 first proposed by Michael Negard to
6:40 maintain an organized timeline of
6:42 decisions providing context around the
6:45 problems addressed the solution adopted
6:48 and the reasons behind those choices. An
6:51 invaluable aspect of ADRs lies in how
6:53 they facilitate informed decision making
6:57 in the future. By summarizing choices in
7:00 an accessible format, ADRs serve as a
7:04 guideposts around past decisions. This
7:06 understanding minimizes duplication and
7:09 fosters consistency as developer can
7:11 refer back to this decision when facing
7:13 similar conundrums. Very often I've
7:16 experienced new joiners that were asking
7:18 why a certain decision was made and
7:21 thanks to ADR I was able to immediately
7:25 provide context and clear understandings
7:27 and insights why certain things were
7:29 happening. ADR also improved project
7:32 continuity as they offer a detailed
7:33 understanding of why specific decisions
7:36 were made. This is crucial especially in
7:38 large projects or organization where
7:40 team members might change over time or
7:42 are spread across the world. Having
7:44 articulated reasoning and clear
7:46 documentation ensures smoother
7:48 transitions and continual progress even
7:51 with new team members on board. ADRs are
7:54 comprehensive. Beyond just recording the
7:57 outcome of a decision, ADRs detail the
8:00 context in which a decision was made and
8:02 context in architecture is everything.
8:05 It also collects alternatives considered
8:06 during the process and potential
8:09 consequences anticipated. This holistic
8:12 view helps developers to understand not
8:15 just the what, but also the why, how,
8:18 and when of decisions. Fostering a more
8:20 profound understanding of the project's
8:22 development path. By openly documenting
8:24 and sharing decision records, it ensures
8:27 that all stakeholders are on the same
8:31 page. This transparency bolsters trust,
8:33 facilitates collaboration, and leads to
8:35 more cohesive development efforts. In
8:38 conclusion, ADRs serve as a powerful
8:40 tool for improving project management
8:41 and decision making in software
8:44 development. I use ADRs many times in my
8:46 project even with customers. I also ask
8:48 multiple teams to write down important
8:50 decisions on ADR. Bear in mind that you
8:52 don't have to create an ADR for every
8:54 single decision you make. But the
8:57 important one that impacts the direction
8:59 of travel of a tech department is a
9:02 mandatory for me. For example, imagine
9:04 you are embarking a modernization
9:06 journey and you have to define at the
9:08 beginning the guard race for the whole
9:11 organization. Things like version
9:13 control strategy, observability,
9:15 communication between microservices,
9:18 security, a specific pattern that you
9:19 want to integrate with the third party
9:22 system and so on. These are great
9:24 candidates for an architecture decision
9:26 record. There are several templates
9:29 available to define an ADR. I provide a
9:31 link in the description below. So bear
9:33 in mind there isn't just a single
9:35 approach. Find the one that fits you
9:37 better. Next up is the request for
9:40 comments or RFC. A comprehensive and
9:42 effective communication process used to
9:45 capture feedback suggestions or
9:47 standardization around a particular
9:49 technology system or protocol. The RFC
9:51 process served to improve the
9:52 understanding and applicability of a
9:55 concept through a widely accessible
9:58 mechanism. It enable experts, developers
10:01 and every other stakeholder for a
10:04 project to contribute with their
10:06 insights. This in turn enhances the
10:09 overall quality of a particular proposal
10:12 or standard. This collaborative approach
10:14 allows for crucial refinements and
10:16 optimization which would have been
10:19 challenging to achieve solely by the
10:23 initial author. Additionally, RFC's help
10:25 to promote discussion and consensus
10:27 building within the community, fostering
10:29 a shared understanding around the
10:31 subject matter. The open nature of the
10:34 RFC process not only encourages fresh
10:36 perspective and innovative ideas, but
10:38 also provides valuable feedback for the
10:40 author. By embracing constructive
10:42 criticism, potential issues and
10:45 alternative ideas, RFC's can evolve into
10:47 a more robust and comprehensive
10:50 standards and protocols. In fact, in
10:52 many open source projects, you can
10:54 propose new features via RFC's.
10:57 Moreover, as RFC's progress through
10:59 discussion, reviews, and revision, they
11:01 serve as a reliable source of
11:04 documentation and learning. They
11:06 document the rationale behind proposed
11:08 solution, keeping an historical record
11:10 of the development process and the
11:12 decision made along the way. This
11:14 information can be particularly useful
11:16 for new team members or other
11:18 professionals looking to gain insight in
11:20 specific technologies or standards. A
11:23 great advantage of RFC is that they
11:25 enables an asynchronous communication
11:26 where everyone can join the
11:29 conversation. Everyone is different.
11:31 There are introverts, extroverts, there
11:33 is maybe a wrong day for a person and
11:35 not everyone performs great during a
11:38 meeting. RFC's as an asynchronous
11:41 mechanism to collect ideas and feedback
11:43 bypass all these challenges because
11:45 usually it's time boxed and allows
11:47 everyone to express their thoughts. I've
11:50 seen teams using RFC even to discuss API
11:53 evolution so all the consumers of an API
11:55 can share their requirements and propose
11:57 new ideas. Most of the time RFC's are
12:00 storing the version of control system
12:03 GitHub, GitLab and similar. So everyone
12:05 in tech department has access and can
12:07 contribute. In summary, the request for
12:09 comments process enriches the
12:11 understanding of technology systems and
12:14 protocols by engaging a wide array of
12:17 experts feedback and fostering a
12:18 collaborative approach to problem
12:21 solving. As these perspectives merge and
12:24 evolve, RFC became a powerful repository
12:27 of knowledge. Also in this case, I left
12:29 a link to RFC template in the
12:30 description below. Now let's move to
12:32 another technique called eventtorming.
12:34 It's a powerful workshop technique
12:37 developed by Alberto Brandolini aims to
12:39 enhance the understanding design and
12:42 modeling of business domains by focusing
12:44 on domain events which represents
12:46 significant changes in the domain.
12:49 Eventtorming serves as a visual and
12:51 collaborative exploration that invites
12:54 various stakeholders to work together in
12:56 creating a common understanding of the
12:59 business process. I've joined several
13:01 events session in the past and I can
13:04 tell you that is unvaluable what you can
13:06 get out of that. One of the core
13:08 strengths of eventstorming is that it
13:11 fosters a unified understanding by
13:13 bringing together every participant from
13:16 business experts to developers. Eventing
13:18 goes further by promoting a naturally
13:20 collaborative dynamic where every
13:22 participant's viewpoint is acknowledged
13:25 and incorporated. In essence, the
13:27 process creates an environment where the
13:29 intersection of ideas between different
13:32 minds, technical and non-technical,
13:33 crafts a share understanding of
13:37 realities. This is the perfect way to
13:39 align the business requirements with the
13:41 technical implementation. Very often I
13:44 have seen people that forget that what
13:47 we are coding is not just code is
13:50 generating value for your customers, for
13:52 the people that are using your software.
13:55 This is a fundamental catch. What goes
13:58 in production is the understanding or
14:01 misunderstanding of developers as well
14:04 said by Brandolini. Having product
14:06 people in the same room of developers
14:09 removes the barriers of just thinking to
14:11 the technical side and we can start to
14:14 focus more on the business outcomes and
14:17 focusing on your customers. That's the
14:19 key learning of this approach. This
14:22 methodology works perfectly with domain
14:24 driven design or DDD as specifying key
14:27 domain events can lead identifying DDD
14:29 constructs such as aggregates or bounded
14:32 context. These insights become pivotal
14:34 when designing and implementing
14:36 efficient software. It starts with a
14:39 broad exploration of code the big
14:41 picture followed by more detailed
14:44 exploration supporting a flexible and
14:46 agile adoption of the insight extracted
14:49 from the process. Finally, eventtorming
14:52 is a potent learning tool and a fast
14:54 user-friendly way to model a domain. Be
14:56 it a new project or an existing
14:57 architecture requiring improvements,
14:59 eventorming enables better clarity with
15:02 effectiveness. Very often during an
15:04 eventtorming session, developers add the
15:06 opportunity to tweak a feature and make
15:08 it easier to implement, reducing the
15:11 friction with the product team and
15:14 creating a synergy within the extended
15:16 team instead of creating silos between
15:18 departments. I used eventtorming for on
15:20 boarding new developers in a team for
15:23 clarifying how to evolve a specific
15:25 domain and even to model complex
15:28 features that touch multiple domains if
15:30 not the entire system. Often people
15:32 think it might be a waste of time. After
15:34 trying one or two days of even storming
15:37 session, I got customers telling me that
15:39 these techniques did in two days what
15:42 they were used to do in five months.
15:45 Don't underestimate this approach
15:47 because it's a musth have in particular
15:49 parts of the software for making sure
15:51 that what is built is what the business
15:54 expects and is delivered with clear
15:57 objectives in mind and possibly on time.
15:59 In the video description, I've added
16:02 also a link about eventtorrming if you
16:04 want to deep dive into the topic. Last
16:08 but not least, the C4 model created by
16:10 software architect Simon Brown is a
16:12 powerful approach to visualizing and
16:15 documenting a systems architecture. It
16:17 stands for context, container,
16:20 component, and code and presents a
16:21 multi-layered view of software
16:23 architecture making it more accessible
16:25 of different stakeholders depending on
16:27 their requirements. The simplicity of
16:30 the C4 model makes it easy to understand
16:32 and apply, bringing a wealth of benefits
16:35 to the software development process. One
16:38 key advantage of the C4 model is its
16:40 layer structure, allowing for a diverse
16:42 understanding according to stakeholders
16:44 needs. For instance, non-technical
16:46 stakeholders might find the context
16:49 layer enough for understanding what
16:51 they're looking for. Furthermore, this
16:54 model encourages to use of common
16:56 language annotation, reducing
16:58 misinterpretation and fostering a shared
17:01 understanding among team members. It
17:03 enables effective knowledge transfer
17:05 across the team, making it easier for
17:07 new members to understand the software
17:08 architecture from different point of
17:11 view. By visualizing complex systems,
17:13 the C4 model supports architectural
17:15 design decisions. It highlights
17:18 potential issues, dependencies, or areas
17:19 of improvements that might not have been
17:22 as apparent in the code alone, leading
17:24 to well-informed decisions. In
17:26 conclusion, the C4 model simplifies
17:28 understanding of complex software
17:31 systems by breaking them down into more
17:34 manageable communicable components. In
17:36 my experience, I've seen just one
17:38 challenge with this model. The fourth C
17:41 code refers to the code diagram that
17:43 tends to get out of date very quickly.
17:45 So watch out and make sure your drying
17:48 arms are up to date. Obviously this one
17:51 is one of the many approaches but I
17:52 believe it's one of the most pragmatic.
17:54 As you have seen I didn't provide you
17:57 with just one technique but several of
18:00 them. You will discover how much impact
18:01 good documentation has during the
18:03 software development life cycle. And
18:05 when it happens I encourage you to write
18:07 down your experience in the comments
18:09 below. Investing time in software
18:11 modeling is not a waste of time. Thanks
18:13 to that you are going to have a
18:16 comprehensive understanding of what you
18:19 need to codify of translate into code
18:22 and you will be able to reach your goal
18:26 faster. So happy documenting and see you
