feat: migrate skills review desk to astro

2026-09-05 16:54:37 +00:00
parent 107e429fb9
commit 71e4775573
66 changed files with 8184 additions and 96 deletions
@@ -0,0 +1,153 @@
+# PlantUML Diagram Types
+
+The eight diagrams the Confluence page author reaches for, with the
+PlantUML skeleton for each. Pick the type by what the reader needs to
+*do* with the diagram, not by what the data looks like.
+
+| Reader needs | Pick |
+|--------------|------|
+| Trace a request across actors | sequence |
+| Show who owns which service | component |
+| Show static structure / inheritance | class |
+| Show valid states of one object | state |
+| Show branching workflow | activity |
+| Show deployment topology | deployment |
+| Show signal timing / concurrency | timing |
+| Show domain entities | ER |
+
+## Sequence
+
+```
+@startuml
+participant Client
+participant Service
+participant DB
+
+Client -> Service: request
+Service -> DB: query
+DB --> Service: rows
+Service --> Client: response
+@enduml
+```
+
+## Component
+
+```
+@startuml
+[Web] --> [API]
+[API] --> [DB]
+[API] --> [Cache]
+@enduml
+```
+
+For C4, prefer hand-drawn boxes if the BASS PlantUML plugin doesn't ship the
+`C4_Container` stdlib. Test with one diagram before committing to the
+notation.
+
+## Class
+
+```
+@startuml
+class Order {
+  +id: UUID
+  +status: Status
+  +total(): Money
+}
+class LineItem {
+  +sku: string
+  +qty: int
+}
+Order "1" *-- "*" LineItem
+@enduml
+```
+
+## State
+
+```
+@startuml
+[*] --> Draft
+Draft --> Submitted: submit
+Submitted --> Approved: approve
+Submitted --> Rejected: reject
+Approved --> [*]
+Rejected --> [*]
+@enduml
+```
+
+## Activity
+
+```
+@startuml
+start
+:parse input;
+if (valid?) then (yes)
+  :process;
+else (no)
+  :reject;
+  stop
+endif
+:persist;
+stop
+@enduml
+```
+
+## Deployment
+
+```
+@startuml
+node "k8s prod" {
+  [service-a] --> [service-b]
+}
+node "external" {
+  [IdP]
+}
+[service-a] --> [IdP]
+@enduml
+```
+
+## Timing
+
+```
+@startuml
+robust "Client" as C
+robust "Service" as S
+C is Idle
+S is Idle
+@0
+C is Requesting
+@5
+S is Processing
+@10
+S is Idle
+C is Idle
+@enduml
+```
+
+## ER
+
+```
+@startuml
+entity "Order" {
+  *id : UUID
+  --
+  total : Money
+}
+entity "LineItem" {
+  *id : UUID
+  --
+  sku : string
+  qty : int
+}
+Order ||--o{ LineItem : contains
+@enduml
+```
+
+## What is NOT a use case
+
+If the diagram needs prose between boxes, it is not a use case. Use a
+sequence or activity diagram instead.
+
+## When to use multiple diagrams
+
+A page that needs two diagrams is fine. A page that needs five is a wall
+ — split the page.
@@ -0,0 +1,66 @@
+# PlantUML Troubleshooting
+
+Symptoms and fixes for the four classes of rendering failure on BASS
+Confluence.
+
+## Macro renders as plain text
+
+| Cause | Fix |
+|-------|-----|
+| Macro name wrong (`PlantUML`, `Plantuml`) | Use `plantuml`, lowercase |
+| Body inside `<ac:rich-text-body>` | Move to `<ac:plain-text-body>` |
+| Macro opened but not closed | Add the matching `</ac:structured-macro>` |
+| Page is in wiki renderer mode | Re-save in storage format (page properties → editor) |
+
+## Diagram renders empty
+
+| Cause | Fix |
+|-------|-----|
+| `@startuml` / `@enduml` missing | Add both, even if PlantUML accepts bodies without |
+| Body has unescaped `<` / `>` outside CDATA | Wrap entire body in `<![CDATA[ … ]]>` |
+| `!include` points to a stdlib the plugin doesn't ship | Replace with hand-drawn equivalent |
+| File-size limit exceeded (very large diagrams) | Split into multiple diagrams |
+
+## Diagram crops on the right
+
+| Cause | Fix |
+|-------|-----|
+| Width > ~900 px | Split the diagram horizontally into two, or simplify |
+| Long labels on long arrows | Shorten labels; move detail to body text |
+| Padding parameters set too high | Drop `skinparam Padding`, `skinparam Margin` overrides |
+
+## Theme reverts to dark on dark space
+
+| Cause | Fix |
+|-------|-----|
+| Page theme overrides the diagram theme | Use `!theme plain` explicitly at the top of the body |
+| BASS theme override | Hard-code colors with `skinparam` per element |
+
+## C4 / standard library includes fail
+
+| Cause | Fix |
+|-------|-----|
+| Plugin doesn't ship the stdlib | Switch to `component` diagram or hand-drawn boxes |
+| Include URL is blocked by network policy | Mirror the stdlib locally, use `!include /path/to/C4_Container.puml` (only if the plugin supports it) |
+
+## Debugging loop
+
+1. Save the `.puml` body to a file.
+2. Run `plantuml -tpng -checkonly -failfast2 file.puml`.
+3. If local parse fails, the body is wrong — fix the syntax.
+4. If local parse succeeds but Confluence fails, the wrapper is wrong — fix
+   the storage macro form.
+
+## When to give up on PlantUML
+
+- The diagram needs interactivity (hover, click). Confluence PlantUML does
+  not support this.
+- The diagram needs real images (logos, photos). Drop them in via attachment
+  instead.
+- The diagram needs to be edited by non-technical authors. PlantUML is not
+  the right tool.
+
+## When to escalate
+
+- The BASS plugin version changes and breaks a working diagram. Capture the
+  diff, fix the diagram, and update this troubleshooting page.