dbf40c30d8
Add comprehensive documentation for literate programming approach: - Phase 1 guidelines focusing on why/what without implementation - General literate programming principles for code documentation - Project notes explaining wrapper script concept and strategy Decision: Follow literate programming to make the wrapper maintainable and educational. Comments tell the story, code implements it. This foundation enables better collaboration and knowledge transfer. The notes.md establishes the core concept: a reproducible wrapper around the Void installer that automates error-prone LUKS encryption setup while keeping user control over system configuration choices.
1.7 KiB
1.7 KiB
Phase 1 beim Literate Programming
- In dieser Phase wird kein Sourcecode geschrieben; es entstehen nur narrative Kommentartexte.
- Schreibe den literalen Anteil dessen, was umgesetzt werden soll: Warum und Was (Motivation, Konzepte, Entscheidungen, Einschränkungen), nicht das Wie.
- Halte Entscheidungen und Alternativen explizit fest, aber ohne Implementierungsdetails oder API-/Algorithmus-Spezifika.
- Stelle Rückfragen, wenn Dinge unklar sind oder mehrere sinnvolle Optionen bestehen; diese Phase ist ein Dialog zur Klärung.
- Strukturiere die Texte in klaren, kleinen Abschnitten, die später als Kommentarblöcke vor Codeblöcken stehen können.
- Verteile die Texte über mehrere Dateien entsprechend der späteren Modulstruktur; jede Datei erzählt einen zusammenhängenden Abschnitt.
- Zielkriterium: Wenn man den Code entfernt, bleibt die Idee vollständig verständlich.
Vorlage Phase 1 Textblock
- Passe das Kommentar-Praefix an die Zielsprache an (z. B.
#,//,/* */). - Schreibe die Inhalte in technischem Englisch; vermeide Implementierungsdetails.
# === Motivation ===
# <Why this exists and who benefits>
# === Problem Statement ===
# <What needs to change or be achieved>
# === Scope ===
# In scope: <...>
# Out of scope: <...>
# === Concepts ===
# <Key terms and relationships>
# === Decisions ===
# <Decision> because <reason>
# === Alternatives Considered ===
# <Option> rejected because <reason>
# === Constraints ===
# <Operational, legal, performance, security, time>
# === Open Questions ===
# <Unresolved items that need clarification>
# === Success Criteria ===
# <Observable outcomes and acceptance criteria>