Skip to content

Commit af1fb8e

Browse files
committed
Update styling in List and Tables for reverse-engineering-documentation-legacy-systems article
1 parent 371348f commit af1fb8e

3 files changed

Lines changed: 164 additions & 50 deletions

File tree

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
export type Props = {
3+
color: string
4+
classes?: string
5+
size: number
6+
accessible: boolean
7+
focusable: boolean
8+
isListMarker?: boolean
9+
id?: string
10+
}
11+
12+
const { color, classes, size, accessible, focusable, isListMarker, id } = Astro.props
13+
---
14+
15+
<svg
16+
id={id}
17+
xmlns="http://www.w3.org/2000/svg"
18+
class:list={["shrink-0", `w-${size} h-${size}`, `text-${color}`, classes, isListMarker ? "mt-0.5" : ""]}
19+
fill="currentColor"
20+
stroke="none"
21+
viewBox="0 0 24 24"
22+
aria-hidden={accessible ? "false" : "true"}
23+
focusable={focusable ? "true" : "false"}
24+
>
25+
{accessible && <title>Dollar Icon</title>}
26+
<path
27+
stroke-linecap="round"
28+
stroke-linejoin="round"
29+
stroke-width="2"
30+
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"
31+
></path>
32+
</svg>

‎src/content/articles/reverse-engineering-documentation-legacy-systems/index.mdx‎

Lines changed: 53 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ featured: true
1111

1212
*[ADR]: Architecture Decision Record
1313

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.
1515

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.
1717

1818
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.
1919

@@ -161,56 +161,99 @@ This knowledge has an expiration date: when the person leaves. Extracting it req
161161
For __architectural knowledge__:
162162

163163
<List
164-
variant="check-icons-list"
164+
variant="three-column-icon-list"
165+
size={7}
166+
classes={{
167+
text: "italic font-semibold",
168+
}}
165169
items={[
166170
{
167171
text: '"What happens when a user places an order?"',
172+
icon: "paper-and-pen",
173+
color: "info",
174+
bgColor: "info-inverse",
168175
},
169176
{
170177
text: '"What breaks if the payment service goes down?"',
178+
icon: "dollar",
179+
color: "warning",
180+
bgColor: "warning-inverse",
171181
},
172182
{
173183
text: '"What\'s the scariest part of this codebase to change?"',
184+
icon: "git",
185+
color: "danger",
186+
bgColor: "danger-inverse",
174187
},
175188
]}
176189
/>
177190

178191
For __operational knowledge__:
179192

180193
<List
181-
variant="check-icons-list"
194+
variant="three-column-icon-list"
195+
size={7}
196+
classes={{
197+
text: "italic font-semibold",
198+
}}
182199
items={[
183200
{
184201
text: '"What pages you most often at night?"',
202+
icon: "on-call",
203+
color: "secondary",
204+
bgColor: "blue-100",
185205
},
186206
{
187207
text: '"What manual steps do deployments require?"',
208+
icon: "wrench",
209+
color: "success",
210+
bgColor: "success-inverse",
188211
},
189212
{
190213
text: '"Where do you look first when API responses slow down?"',
214+
icon: "api",
215+
color: "primary-offset",
216+
bgColor: "gray-200",
191217
},
192218
]}
193219
/>
194220

195221
For __business rules encoded in code__:
196222

197223
<List
198-
variant="check-icons-list"
224+
variant="three-column-icon-list"
225+
size={7}
226+
classes={{
227+
text: "italic font-semibold",
228+
}}
199229
items={[
200230
{
201231
text: '"What business rules live in code but not in any document?"',
232+
icon: "gear",
233+
color: "accent",
234+
bgColor: "purple-100",
202235
},
203236
{
204237
text: '"What edge cases have special handling?"',
238+
icon: "external",
239+
color: "orange-700",
240+
bgColor: "orange-100",
205241
},
206242
{
207243
text: '"What compliance requirements shaped this code?"',
244+
icon: "shield",
245+
color: "success",
246+
bgColor: "green-100",
208247
},
209248
]}
210249
/>
211250

212251
<Table
213-
variant="vertical-column-delineation-table"
252+
variant="minimal-borders-table"
253+
fullWidth={false}
254+
classes={{
255+
figure: "mt-18 mb-6",
256+
}}
214257
content={{
215258
thead: {
216259
th: ['Interview Focus', 'Best Participants', 'Knowledge Domain'],
@@ -250,7 +293,10 @@ Capture tribal knowledge __before__ someone announces they're leaving. By the ti
250293
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:
251294

252295
<List
253-
variant="check-icons-list"
296+
variant="chevron-list"
297+
classes={{
298+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
299+
}}
254300
items={[
255301
{
256302
lead: 'The dangerous parts',

0 commit comments

Comments
 (0)