The document discusses the detrimental effects of informal decision-making, also referred to as tribal knowledge, which can lead to a lack of transparency, accountability, and increased technical debt. It proposes a structured approach to design decisions that includes clearly defining context, problems, solution proposals, and success metrics, alongside utilizing Requests for Comments (RFCs) to promote consensus and clarity. By documenting decisions formally, organizations can mitigate risks associated with informal processes and improve overall team alignment and system maintainability.

1. Informal decision-making
is *considered harmful!
* https://en.wikipedia.org/wiki/Considered_harmful
by Hamid Davoodi

2. Imagine a very likely scenario
● Moved to a new team in your current company
● Working on a new project in the same team
● You are asked to cover someone for a while
● Work with some other team to fix an issue
● Moving to a new company
● Went to coma and woke up 6 month later

3. To not reinvent the wheel
We ask questions!

4. You’d have many questions!
● Why gRPC over web?
● Why NodeJS over Java?
● Why Scala over Java?
● Why DC over Cloud?
● Why Cloud over DC?
● Why NoSQL over ACID?
● Why RabbitMQ and not Kafka?
● Why a new API?
● Why CDN over API?
● Why RMQ has only one instance?
● Why this particular database?
● Why PostgreSQL over Redis?

5. But any answers?
➔ I don’t know, Ask Jim, he probablyknows why
➔ Alex did that, he left the company
➔ I have no idea!You tell me
➔ That was a mistakebecause …
➔ It’s probablybecause of …
➔ EMs decided that and I don’t know/rememberwhy.

6. What was the objective?
● What the problem was?
● What about alternative solutions?
● What was risk mitigation strategy?
● Did it achieve the end goal?
● Was it worth it?
We don’t know :(

7. Why?
● Bus Factor
● Personal Bias
● No preserved history
● No measurement
● Hype Driven Development
● Informal Conversations
It’s “forgotten” history

8. All we know is that
A Solution
to
A Problem
It was a
Design
Decision
=

9. What’s to blame?!
Informal Decision-Making
aka
Tribal Knowledge

10. Tribal Knowledge
Or informal knowledge refers to the unwritten, unspoken, and often
implicit understanding, skills, and practices that exist within a group or
organization.
https://en.wikipedia.org/wiki/Tribal_knowledge
https://devblogs.microsoft.com/premier-developer/tribal-knowledge-the-anti-devops-culture/

11. Why is Tribal Knowledge a thing?
It’s Faster
in the short term!
Delegating to a few
It’s easier
Agile?!

12. Why is Tribal Knowledge a thing?
It’s faster in the short term!
However, It leads to longer-term issues in
code quality,
team alignment,
and system maintainability.

13. Tribal Knowledge’s risks:
● Lack of transparency:
Decisions may be made without all stakeholders being aware or having input.
● Inconsistency:
Without a formal process, similar issues might be handled differently each time.
● Limited perspective:
Quick, informal decisions often don't benefit from diverse viewpoints or expertise.
● Poor documentation:
The reasoning behind decisions may not be recorded, leading to confusion later.
● Miscommunication:
Important details or considerations can be easily overlooked or misunderstood.

14. Tribal Knowledge’s risks:
● Difficulty in scaling:
As teams grow, informal processes become less effective and more prone to errors.
● Reduced accountability:
It's harder to track who made what decision and why.
● Increased technical debt:
Hasty, undocumented decisions can lead to suboptimal solutions that cause problems later.
● Missed opportunities for improvement:
Without a formal review process, chances to refine ideas are often lost.
● Risk of bias:
Informal processes may favor the loudest voices or highest-ranking team members, rather
than the best ideas.

15. Solution?
● Preserve History
● Spread Awareness
● Gather Feedback
● Reach Consensus
https://peps.python.org/pep-0020/ = Explicit is better than implicit
Design Decisions

16. Back to basics
Solution(s)
to
Problem(s)
On the way of
An Objective
A
Design
Decision
=

17. What’s a problem?
Any obstacles
preventing us from reaching
an objective.

18. What’s a solution?
Any
tools/strategies/implementations
that help us to
overcome a problem
in the context of reaching an objective.

19. What’s an objective?
A specific and
measurable goal
to achievewithin a defined
timeframe.

20. Let’s propose
a document structure for
Design Decisions.

21. To document a Design Decision:
● Context:
Define what’s the current state and
the objective to reach

22. To document a Design Decision:
● Problems:
Find all obstacles on our way to
reach the objective

23. To document a Design Decision:
● Solution proposal:
The least riskiest solution for the
most obstacles

24. To document a Design Decision:
● Alternatives:
List all the other feasible solutions

25. To document a Design Decision:
● Risks and mitigations:
List mitigations on risks of the
chosen solution(s)

26. To document a Design Decision:
● Cost factors:
Define Timeline, Estimations,
Budget

27. To document a Design Decision:
● Success metrics:
Evaluate how to conclude

28. Structured Design Decision
● Context: Define what’s the current state and an objective to reach
● Problems: Find all obstacles on our way to reach the goal
● Solution proposal:
Choose the least riskiest solution for the most obstacles by comparison
● Alternatives: List all the possible solutions
● Risks and mitigations: List mitigations on risks of the chosen solution(s)
● Cost factors: Define Timeline, Estimations, Budget
● Success metrics: Evaluate how to conclude

29. Request For Comments (RFC)
A formal document proposing a new feature, process, or
major change in any topic or scope, intended to gather
feedback and reach consensus before implementation.
https://en.wikipedia.org/wiki/Request_for_Comments

30. RFC structure
● Context
● Problems
● Proposal
● Alternatives
● Risks and mitigations
● Timeline, Estimations, Cost
● Success metrics
Don’t forget to:
1. Share it
2. Ask for feedbacks
3. Reach consensus
4. Publish it

31. RFC Process

32. An interesting tool for RFCs:
Architectural Design Records
adr.github.io

33. Another process!? You anti-agile monster!
Let’s go through agile principles:
● Individuals and interactions OVER processes and tools
● Working software OVER comprehensive documentation
● Customer collaboration OVER contract negotiation
● Responding to change OVER following a plan

34. Isn’t this against Agile?! Nope.
RFCs can align with agile principles by:
● Promoting transparency and collaboration
● Encouraging early feedback on significant changes
● Providing a mechanism for continuous improvement

35. To maintain agility, RFC process should be:
● Lightweight and flexible
● Used selectively for significant decisions
● Time-boxed to prevent analysis paralysis
● Focused on outcomes rather than extensive
documentation

36. Don’t we already have this?!
● New feature? Yes, Jira + Github
● Processes? No.
● Architectural
Decisions? No!

37. Why RFCs?
● Clarifies what the objective, explicitly, is
● Refine what the problems are
● Test and confirm your idea
● Eradicates jumping to conclusions
● No Tribal Knowledge
● Easier to ask for a change
● Synchronization with other teams

38. Right?!
RFC > Meeting

39. Please tell me
Based on
which RFC
did you make a
Design Decision?
Objective?
Problem?
Success
Metrics?
Solution?

40. We can do it, too.
Link

41. Thanks
Questions?
References
https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/
https://www.industrialempathy.com/posts/design-docs-at-google/
https://blog.pragmaticengineer.com/rfcs-and-design-docs/

42. What do YOU think?
Now what?