You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit af1fb8e
Browse filesBrowse the repository at this point in the historyBrowse files
d="M 13.091417,10.854545 V 4.6363636 A 8.4,8.4 0 0 1 15.927781,5.7818182 1.2,1.2 0 0 0 17.61869,5.4 0.98181818,0.98181818 0 0 0 17.400508,3.8181818 9.3272727,9.3272727 0 0 0 13.091417,2.2909091 v -1.2 a 1.0909091,1.0909091 0 0 0 -2.181818,0 v 1.0909091 c -3.4363628,0.2727273 -5.8909088,2.4 -5.8909088,5.2909091 v 0 c 0,3.2727277 2.345455,4.5818177 5.8909088,5.4545457 v 6.490909 a 9.1090909,9.1090909 0 0 1 -3.9818178,-1.690909 1.0909091,1.0909091 0 0 0 -1.636364,0.218182 c -0.545454,0.70909 -0.490909,1.254545 0.05455,1.636363 a 10.8,10.8 0 0 0 5.5636358,2.127273 v 1.2 a 1.0909091,1.0909091 0 0 0 2.181818,0 v -1.145455 c 3.545455,-0.272727 6,-2.4 6,-5.454545 v 0 c 0,-2.836364 -1.8,-4.472727 -6,-5.454546 z M 7.6368722,7.3636364 v 0 c 0,-1.5272728 1.309091,-2.6181819 3.2727268,-2.7818182 V 10.363636 C 8.1823262,9.6 7.6368722,8.672727 7.6368722,7.3636364 Z m 8.8363638,9.1636366 c 0,1.581818 -1.363637,2.727272 -3.381819,2.945454 v -6 c 2.781819,0.763637 3.381819,1.690909 3.381819,3 z"
Copy file name to clipboardExpand all lines: src/content/articles/reverse-engineering-documentation-legacy-systems/index.mdx
+53-7Lines changed: 53 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,9 +11,9 @@ featured: true
11
11
12
12
*[ADR]: Architecture Decision Record
13
13
14
-
You've inherited a system with a README that was last updated three years ago. The architecture diagrams reference services that no longer exist. The wiki has seventeen conflicting pages about deployment, and no one's sure which ones are current. The original architects left two reorganizations ago.
14
+
You've inherited a system with a `README` that was last updated three years ago. The architecture diagrams reference services that no longer exist. The wiki has seventeen conflicting pages about deployment, and no one's sure which ones are current. The original architects left two reorganizations ago.
15
15
16
-
Here's the uncomfortable truth: outdated documentation isn't just unhelpful — it's actively harmful. When a new team member reads that architecture diagram and forms a mental model of how the system works, they're building on outdated assumptions that will take months to unlearn. When an on-call engineer follows a runbook during an incident, they might make things worse by following steps that no longer apply.
16
+
<Highlighter>Here's the uncomfortable truth: outdated documentation isn't just unhelpful — it's actively harmful.</Highlighter> When a new team member reads that architecture diagram and forms a mental model of how the system works, they're building on outdated assumptions that will take months to unlearn. When an on-call engineer follows a runbook during an incident, they might make things worse by following steps that no longer apply.
17
17
18
18
But there's good news. The codebase itself contains more reliable documentation than any wiki page ever will. Git history records what changed, when, and often why. Tests that pass demonstrate working behavior that prose documentation might get wrong. And the engineers who've kept the system alive hold knowledge that's never been written down.
19
19
@@ -161,56 +161,99 @@ This knowledge has an expiration date: when the person leaves. Extracting it req
161
161
For __architectural knowledge__:
162
162
163
163
<List
164
-
variant="check-icons-list"
164
+
variant="three-column-icon-list"
165
+
size={7}
166
+
classes={{
167
+
text: "italic font-semibold",
168
+
}}
165
169
items={[
166
170
{
167
171
text: '"What happens when a user places an order?"',
172
+
icon: "paper-and-pen",
173
+
color: "info",
174
+
bgColor: "info-inverse",
168
175
},
169
176
{
170
177
text: '"What breaks if the payment service goes down?"',
178
+
icon: "dollar",
179
+
color: "warning",
180
+
bgColor: "warning-inverse",
171
181
},
172
182
{
173
183
text: '"What\'s the scariest part of this codebase to change?"',
184
+
icon: "git",
185
+
color: "danger",
186
+
bgColor: "danger-inverse",
174
187
},
175
188
]}
176
189
/>
177
190
178
191
For __operational knowledge__:
179
192
180
193
<List
181
-
variant="check-icons-list"
194
+
variant="three-column-icon-list"
195
+
size={7}
196
+
classes={{
197
+
text: "italic font-semibold",
198
+
}}
182
199
items={[
183
200
{
184
201
text: '"What pages you most often at night?"',
202
+
icon: "on-call",
203
+
color: "secondary",
204
+
bgColor: "blue-100",
185
205
},
186
206
{
187
207
text: '"What manual steps do deployments require?"',
208
+
icon: "wrench",
209
+
color: "success",
210
+
bgColor: "success-inverse",
188
211
},
189
212
{
190
213
text: '"Where do you look first when API responses slow down?"',
214
+
icon: "api",
215
+
color: "primary-offset",
216
+
bgColor: "gray-200",
191
217
},
192
218
]}
193
219
/>
194
220
195
221
For __business rules encoded in code__:
196
222
197
223
<List
198
-
variant="check-icons-list"
224
+
variant="three-column-icon-list"
225
+
size={7}
226
+
classes={{
227
+
text: "italic font-semibold",
228
+
}}
199
229
items={[
200
230
{
201
231
text: '"What business rules live in code but not in any document?"',
232
+
icon: "gear",
233
+
color: "accent",
234
+
bgColor: "purple-100",
202
235
},
203
236
{
204
237
text: '"What edge cases have special handling?"',
238
+
icon: "external",
239
+
color: "orange-700",
240
+
bgColor: "orange-100",
205
241
},
206
242
{
207
243
text: '"What compliance requirements shaped this code?"',
@@ -250,7 +293,10 @@ Capture tribal knowledge __before__ someone announces they're leaving. By the ti
250
293
With git history mined, tests written, and interviews conducted, the question becomes: what do you document first? You can't cover everything, and you shouldn't try. Focus on three categories:
0 commit comments