1 of 221

Unlocking the Complexity of Documentation Creation: Perspectives, Challenges, and Criticality in a Large Organization

Rafał Schmidt

2 of 221

Unlocking the Complexity of Documentation Creation: Perspectives, Challenges, and Criticality in a Large Organization

Rafał Schmidt

Once again hello everyone, hope you enjoyed the conference so far, really happy that you decided to join this session.

Today we will delve into the realm of technical documentation creation within the context of a large organization such as Allegro.

As is said It’s a great pleasure to speak in front of you so let’s get into it!

—

But before we actually start, let me quickly introduce myself.

I’m a software engineer with hands-on experience in creating web applications and server-side services with a broad knowledge of the Microsoft technology stack including Azure Cloud. I work at Allegro Pay where we build one of the fastest growing FinTech in Poland. I typically spends his spare time on bike trips and books

—

We will explore the intended audience, the content that demands description, the varying perspectives at play, and the tools employed in the process.

3 of 221

I've never heard (from devs)

4 of 221

5 of 221

6 of 221

7 of 221

7

8 of 221

8

9 of 221

9

10 of 221

10

?

11 of 221

New solution?

12 of 221

Features?

13 of 221

Features?

Restrictions?

14 of 221

Features?

Restrictions?

Alternatives?

15 of 221

Features?

Restrictions?

Alternatives?

Credibility?

16 of 221

Features?

Restrictions?

Alternatives?

Credibility?

It depends…

17 of 221

Well written?

It depends…

18 of 221

First

impression

19 of 221

Unclear

20 of 221

21 of 221

22 of 221

23 of 221

24 of 221

Unclear

Null

25 of 221

26 of 221

27 of 221

28 of 221

29 of 221

30 of 221

31 of 221

32 of 221

32

33 of 221

33

34 of 221

34

35 of 221

Unclear

Null

Obvious

36 of 221

Lesson?

37 of 221

38 of 221

39 of 221

40 of 221

41 of 221

Array.prototype.reduce()

42 of 221

Wrap up…

43 of 221

?

44 of 221

?

45 of 221

Goal

46 of 221

1. Target groups - “who”

Goal

47 of 221

1. Target groups - “who”

2. Use cases - “what”

Goal

48 of 221

1. Target groups - “who”

2. Use cases - “what”

3. Tooling - “how”

Goal

The primary goal of this presentation is to provide insights into our documentation practices, with a focus on enhancing our approach. We aim to achieve the following objectives:

1. Target Groups ("Who"): We will identify the diverse audiences for our documentation and emphasize the importance of tailoring our documentation to meet their needs.

2. Use Cases ("What"): We will delve into the various use cases for our documentation, illustrating its practical applications and benefits across different scenarios.

3. Tooling ("How"): We will explore the tools and techniques that can streamline the documentation process, making it more efficient and effective.

Someone from the audience could suggest another one which is “why” - Why do we document at all? Is documentation truly necessary for our projects?

49 of 221

Why?

50 of 221

51 of 221

52 of 221

52

53 of 221

Target groups - “who”

54 of 221

55 of 221

56 of 221

57 of 221

57

58 of 221

58

New hires

59 of 221

59

60 of 221

60

61 of 221

61

62 of 221

Bulletproof?

63 of 221

63

64 of 221

64

65 of 221

65

66 of 221

Loop?

67 of 221

67

68 of 221

68

69 of 221

69

70 of 221

70

71 of 221

Loop

71

72 of 221

Responsibility?

73 of 221

73

74 of 221

74

75 of 221

75

76 of 221

Target groups - “who”

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

77 of 221

You

Target groups - “who”

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

78 of 221

You

Team devs

Target groups - “who”

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

79 of 221

You

Team devs

Testers

Target groups - “who”

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

80 of 221

You

Team devs

Testers

Other devs

Target groups - “who”

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

81 of 221

You

Team devs

Testers

Other devs

Principals

Target groups - “who”

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

82 of 221

You

Team devs

Testers

Other devs

Principals

Target groups - “who”

Analysts

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

83 of 221

You

Team devs

Testers

Other devs

Principals

Target groups - “who”

Analysts

Business

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

84 of 221

You

Team devs

Testers

Other devs

Principals

Target groups - “who”

Analysts

Business

On duty

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

85 of 221

You

Team devs

Testers

Other devs

Principals

Target groups - “who”

Analysts

Business

On duty

Compliance

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

86 of 221

You

Team devs

Testers

Other devs

Principals

Target groups - “who”

Analysts

Business

On duty

Compliance

Auditors

It's crucial to consider your target audience. Here are the groups who may benefit if you decide to tailor the content for them:

You: As the author, it starts with you. Clear documentation can save you time and effort in the long run.

Team Developers: Your team members rely on it to collaborate effectively.

Testers: Testers need well-documented procedures to carry out comprehensive testing.

Other Developers: Beyond your team, other developers may need to interact with your work, especially in cross-team initiatives.

Principals: They often refer to it to ensure alignment.

Analysts: Those responsible for analyzing and improving processes may use documentation as a valuable starting point.

Business: Documentation can bridge the gap between technical and non-technical stakeholders.

On-Duty Engineers: In case of incidents, clear documentation helps on-duty staff troubleshoot effectively.

Compliance Teams: Regulatory compliance often requires some documentation as a contribution to the contract.

Auditors: External auditors may review your documentation for compliance purposes.

Remember, if your documentation is exceptional, it might serve as a role model for other teams. Conversely, if it's weak, even your own team may choose to ignore it.

87 of 221

Use cases - “what”

(mixed with recommendations)

88 of 221

89 of 221

90 of 221

91 of 221

92 of 221

stackoverflow = �

93 of 221

stackoverflow = target_group� * use_cases

94 of 221

stackoverflow = target_group � * use_cases� * living_doc_ratio

95 of 221

problem?

96 of 221

comprehensive

enough

97 of 221

comprehensive

enough

easily accessible

98 of 221

comprehensive

enough

easily accessible

living (new hires fixes)

99 of 221

99

100 of 221

100

101 of 221

101

102 of 221

102

103 of 221

103

104 of 221

104

105 of 221

105

106 of 221

Automatic?

107 of 221

107

108 of 221

examples?

109 of 221

110 of 221

111 of 221

112 of 221

113 of 221

114 of 221

115 of 221

115

116 of 221

116

117 of 221

117

118 of 221

119 of 221

120 of 221

121 of 221

122 of 221

123 of 221

124 of 221

125 of 221

126 of 221

126

The P3 Model (introduced by him) offers deep and up-to-date insights into various aspects of a system.

The name "P3 Model" derives from three primary perspectives through which we can examine a software system:

Domain: This perspective focuses on understanding the domain model, which is crucial for effective software design and development.

Technology: Technical considerations are vital, but they are not the sole factor in designing and maintaining a software system. The technology perspective provides insights into the technical aspects of the system.

People: Recognizing the importance of the human element in software development, the P3 Model includes information about the people involved in the project and the relationships between these individuals and the elements of the system.

127 of 221

The P3 Model (introduced by him) offers deep and up-to-date insights into various aspects of a system.

The name "P3 Model" derives from three primary perspectives through which we can examine a software system:

Domain: This perspective focuses on understanding the domain model, which is crucial for effective software design and development.

Technology: Technical considerations are vital, but they are not the sole factor in designing and maintaining a software system. The technology perspective provides insights into the technical aspects of the system.

People: Recognizing the importance of the human element in software development, the P3 Model includes information about the people involved in the project and the relationships between these individuals and the elements of the system.

128 of 221

The P3 Model (introduced by him) offers deep and up-to-date insights into various aspects of a system.

The name "P3 Model" derives from three primary perspectives through which we can examine a software system:

Domain: This perspective focuses on understanding the domain model, which is crucial for effective software design and development.

Technology: Technical considerations are vital, but they are not the sole factor in designing and maintaining a software system. The technology perspective provides insights into the technical aspects of the system.

People: Recognizing the importance of the human element in software development, the P3 Model includes information about the people involved in the project and the relationships between these individuals and the elements of the system.

129 of 221

The P3 Model (introduced by him) offers deep and up-to-date insights into various aspects of a system.

The name "P3 Model" derives from three primary perspectives through which we can examine a software system:

Domain: This perspective focuses on understanding the domain model, which is crucial for effective software design and development.

Technology: Technical considerations are vital, but they are not the sole factor in designing and maintaining a software system. The technology perspective provides insights into the technical aspects of the system.

People: Recognizing the importance of the human element in software development, the P3 Model includes information about the people involved in the project and the relationships between these individuals and the elements of the system.

130 of 221

The P3 Model (introduced by him) offers deep and up-to-date insights into various aspects of a system.

The name "P3 Model" derives from three primary perspectives through which we can examine a software system:

Domain: This perspective focuses on understanding the domain model, which is crucial for effective software design and development.

Technology: Technical considerations are vital, but they are not the sole factor in designing and maintaining a software system. The technology perspective provides insights into the technical aspects of the system.

People: Recognizing the importance of the human element in software development, the P3 Model includes information about the people involved in the project and the relationships between these individuals and the elements of the system.

131 of 221

131

132 of 221

132

133 of 221

133

134 of 221

134

135 of 221

135

136 of 221

136

137 of 221

137

138 of 221

138

The American political system is broken into three parts. The Legislative branch consists of the Congress and the Senate and proposes legislation.

Adapted from Political System of the United States, by 111Alleskönner (CC BY-SA 3.0 DE)

Legislators are elected by the American people. The Executive branch carries out the legislation, and consists of the President, the Vice President, the Cabinet and the Armed Forces. The Cabinet represents 15 departments, and these representatives are appointed directly by the President, but need to be approved by Congress. The Judicial branch evaluates legislation. The supreme court representatives are appointed directly by the President. Both the President and the Supreme Court can veto or appeal legislation. The American people elect people into the Electoral College, who then elect the President, and the Vice President. In addition to the federal political system, states have their own courts, legislators and governors.

using text

139 of 221

139

The American political system is broken into three parts. The Legislative branch consists of the Congress and the Senate and proposes legislation.

Adapted from Political System of the United States, by 111Alleskönner (CC BY-SA 3.0 DE)

Legislators are elected by the American people. The Executive branch carries out the legislation, and consists of the President, the Vice President, the Cabinet and the Armed Forces. The Cabinet represents 15 departments, and these representatives are appointed directly by the President, but need to be approved by Congress. The Judicial branch evaluates legislation. The supreme court representatives are appointed directly by the President. Both the President and the Supreme Court can veto or appeal legislation. The American people elect people into the Electoral College, who then elect the President, and the Vice President. In addition to the federal political system, states have their own courts, legislators and governors.

140 of 221

140

vs

141 of 221

141

142 of 221

142

The American political system is broken into three parts. The Legislative branch consists of the Congress and the Senate and proposes legislation.

Adapted from Political System of the United States, by 111Alleskönner (CC BY-SA 3.0 DE)

Legislators are elected by the American people. The Executive branch carries out the legislation, and consists of the President, the Vice President, the Cabinet and the Armed Forces. The Cabinet represents 15 departments, and these representatives are appointed directly by the President, but need to be approved by Congress. The Judicial branch evaluates legislation. The supreme court representatives are appointed directly by the President. Both the President and the Supreme Court can veto or appeal legislation. The American people elect people into the Electoral College, who then elect the President, and the Vice President. In addition to the federal political system, states have their own courts, legislators and governors.

143 of 221

143

144 of 221

144

145 of 221

145

146 of 221

146

draw.io

147 of 221

147

draw.io

mermaid

148 of 221

148

draw.io

mermaid

plantuml

149 of 221

149

d

150 of 221

150

151 of 221

151

152 of 221

152

153 of 221

153

154 of 221

154

155 of 221

155

156 of 221

High-level overview

157 of 221

High-level overview

Principal

158 of 221

High-level overview

Principal

Me

159 of 221

High-level overview

Principal

Me

New hire

160 of 221

160

161 of 221

Architecture

Decision Records

"In the world of architecture and decision-making, there are no inherently 'bad' decisions; there are just those that go unrecorded.

ADRs, short for Architecture Decision Records, are a powerful tool that has garnered global recognition. There's a wealth of existing knowledge and resources available on this topic, so there's no need for us to rehash it here.

ADRs offer us a systematic way to capture and document the decisions we make throughout the architectural journey. They become our trusted companions, helping us understand the 'whys' behind our choices, ensuring clarity, and fostering better collaboration.

As we dive into the world of ADRs, remember that they're not just documents; they're a cornerstone of sound architectural practices. So, let's embrace this valuable tool and use it to our advantage in crafting robust and well-documented architectures."

162 of 221

Architecture

Decision Records

no 'bad' decisions; just unrecorded

"In the world of architecture and decision-making, there are no inherently 'bad' decisions; there are just those that go unrecorded.

ADRs, short for Architecture Decision Records, are a powerful tool that has garnered global recognition. There's a wealth of existing knowledge and resources available on this topic, so there's no need for us to rehash it here.

ADRs offer us a systematic way to capture and document the decisions we make throughout the architectural journey. They become our trusted companions, helping us understand the 'whys' behind our choices, ensuring clarity, and fostering better collaboration.

As we dive into the world of ADRs, remember that they're not just documents; they're a cornerstone of sound architectural practices. So, let's embrace this valuable tool and use it to our advantage in crafting robust and well-documented architectures."

163 of 221

Architecture

Decision Records

no 'bad' decisions; just unrecorded

164 of 221

164

165 of 221

165

166 of 221

166

167 of 221

167

168 of 221

168

Context and Problem

169 of 221

169

Context and Problem
What We Want (and the Deciding Factors)

170 of 221

170

Context and Problem
What We Want (and the Deciding Factors)
What Options We Have (and Their Consequences)

171 of 221

171

Context and Problem
What We Want (and the Deciding Factors)
What Options We Have (and Their Consequences)
Decision

172 of 221

172

173 of 221

173

174 of 221

174

175 of 221

175

ADR != RFC�ADR <> RFC

176 of 221

More use cases

177 of 221

Playbooki / FAQ - on call

More use cases

178 of 221

Playbooki / FAQ - on call

Getting started

More use cases

179 of 221

Playbooki / FAQ - on call

Getting started

How to build, run, run tests

More use cases

180 of 221

Playbooki / FAQ - on call

Getting started

How to build, run, run tests

Access Management

More use cases

181 of 221

Playbooki / FAQ - on call

Getting started

How to build, run, run tests

Access Management

Service's clients�

More use cases

182 of 221

Playbooki / FAQ - on call

Getting started

How to build, run, run tests

Access Management

Service's clients�Researches/PoC results

More use cases

183 of 221

Playbooki / FAQ - on call

Getting started

How to build, run, run tests

Access Management

Service's clients�Researches/PoC results

Summaries of tech initiatives

More use cases

184 of 221

Tooling - “how”

185 of 221

Where?

186 of 221

186

vs

187 of 221

187

vs

188 of 221

188

vs

189 of 221

189

vs

190 of 221

190

vs

191 of 221

Catalog

Now we need to solve the problem of managing and maintaining a growing ecosystem of software components, services, and plugins in a large organization as we have multiple github pages with documentation. As companies expand and their software architecture becomes increasingly complex, it becomes crucial to have a unified and efficient way to manage these components.

Backstage.io provides a centralized hub where teams can discover, catalog, and collaborate on various software assets, including services, APIs, plugins, and more. It offers a unified view of the entire software landscape within an organization, making it easier for developers, engineers, and teams to find, share, and reuse components.

This platform also facilitates collaboration by allowing teams to document and share information about their services, including APIs, documentation, ownership details, and usage guidelines. It promotes best practices, reduces redundancy, and enhances overall productivity.

192 of 221

193 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

194 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

195 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

196 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

197 of 221

�binoculars -> benokjulers

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

198 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

199 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

200 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

201 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

202 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

203 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

204 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

205 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

206 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

207 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

208 of 221

On the left-hand side, you typically find various filters and metadata categories for organizing and refining your search within the catalog. These commonly include:

Kind: This filter allows you to categorize components based on their type or category. For example, you might filter by "Service," "Plugin," "API," or other relevant classifications.

Type: It helps you specify the specific type or subtype of components. For instance, you could filter by "Frontend," "Backend," "Database," etc., depending on the component's nature.

Owner: This filter lets you narrow down components based on their ownership. You can filter by individual teams, departments, or individuals responsible for managing and maintaining a particular component.

Status: This filter helps you identify components based on their current status, such as "Active," "Deprecated," "Archived," etc.

These filters and metadata categories allow users to precisely define their search criteria and efficiently locate the components they need within the catalog.

209 of 221

210 of 221

211 of 221

212 of 221

212

213 of 221

213

214 of 221

214

215 of 221

215

216 of 221

216

217 of 221

1. Target groups - “who”

218 of 221

1. Target groups - “who”

2. Use cases - “what”

219 of 221

1. Target groups - “who”

2. Use cases - “what”

3. Tooling - “how”

220 of 221

Thank you!

Got any questions?�

rafal.schmidt@allegro.com�linkedin.com/in/rafalschmidt

221 of 221

Thank you!

Got any questions?�

rafal.schmidt@allegro.com�linkedin.com/in/rafalschmidt

rafalschmidt.com