Stephan Lo
f797af114b
Configure markdownlint with rules aligned to technical documentation standards and Docsy theme conventions. Design Decisions: - Enable core quality rules (heading hierarchy, consistent list styles) - Allow inline HTML for Docsy shortcodes and components - Permit bare URLs (common in technical documentation) - Make code block language hints optional (pragmatic for existing content) - Set maximum 2 consecutive blank lines (balanced readability) - Enforce single trailing newline (POSIX standard) - Use asterisk for unordered lists (consistency) - Allow 2-space list indentation (Markdown standard) Auto-fixed Issues: - Converted dash lists to asterisk lists (568 fixes) - Removed trailing spaces (211 fixes) - Added missing trailing newlines (74 fixes) - Added blank lines around lists and headings (100+ fixes) Remaining Style Warnings (intentionally accepted): - MD029: List numbering variations in meeting notes (75 instances) - MD036: Bold text for section headers in ADRs (13 instances) - MD025: Multiple H1 in notes/brainstorming docs (10 instances) - MD032/MD022: Minor spacing variations (15 instances) Test Results: ✅ Hugo build: 227 pages generated successfully ✅ HTML validation: No errors ✅ Link checking: All links valid (except dev-only livereload) ✅ Markdown linting: Only non-critical style warnings remain The configuration balances strict quality checks with pragmatic flexibility for diverse content types (documentation, ADRs, meeting notes, tutorials).
1 KiB
1 KiB
why we have architectural documentation
TN: Robert, Patrick, Stefan, Stephan 25.2.25, 13-14h
referring Tickets / Links
- https://jira.telekom-mms.com/browse/IPCEICIS-2424
- https://jira.telekom-mms.com/browse/IPCEICIS-478
- Confluence: https://confluence.telekom-mms.com/display/IPCEICIS/Architecture
charts
we need charts, because:
- external stakeholders (especially architects) want to understand our product and component structure(*)
- our team needs visualization in technical discussions(**)
- we need to have discussions during creating the documentation
(*): marker: "jetzt hab' ich das erste mal so halbwegs verstanden was ihr da überhaupt macht" (**) marker: ????
typed of charts
- schichtenmodell (frontend, middleware, backend)
- bebauungsplan mit abhängigkeiten, domänen
- kontext von außen
- komponentendiagramm,
decisions
- openbao is backend-system, wird über apis erreicht
further topics / new requirements
- runbook (compare to openbao discussions)
- persistenz der EDP konfiguartion (zb postgres)
- OIDC vs. SSI