Einige Dokumentationsdateien gelten sowohl für Konzeptübungen als auch für Praxisübungen. Diese übungsübergreifenden Dateien liegen im Verzeichnis exercises/shared/.docs des Tracks:
-
debug.md: erläutert, wie Lernende, die im Browser programmieren, trotzdem „debuggen“ können (optional)
-
help.md: enthält trackspezifische Anweisungen, wie man Hilfe bekommt (erforderlich)
-
representations.md: erläutert, welche Normalisierungen auf eine Lösung angewendet werden, um ihre Repräsentation zu erstellen (optional)
-
tests.md: enthält trackspezifische Anweisungen, wie man die Tests ausführt (erforderlich)
Das Präsentationsdokument beschreibt, wie diese Dateien verwendet werden, um den Lernenden Inhalte zu präsentieren.
Datei: debug.md
Zweck: Erklärt, wie Lernende, die im Browser programmieren, trotzdem „debuggen“ können
Vorkommen: Optional
Der Editor im Browser hat keine eingebaute Debugging-Unterstützung. Wenn der Test-Runner des Tracks das Erfassen der Konsolenausgabe unterstützt, können Lernende trotzdem eine Art von Debugging betreiben, und dieses Dokument erklärt, wie das geht.
Der Inhalt dieser Datei wird nur im Online-Editor angezeigt; die Kommandozeile ignoriert diese Datei.
Beispiel
# Debug
To help with debugging, you can use the fact that any [console output](https://www.programiz.com/csharp-programming/basic-input-output) will be shown in the test results window. You can write to the console using:
```csharp
Console.WriteLine("Debug message");
```
Datei: help.md
Zweck: Erklärt, wie Lernende Hilfe bekommen können
Vorkommen: Erforderlich
Beschreibe, wie Lernende Hilfe bekommen können, und zwar speziell für diesen Track (nicht für ganz Exercism).
Der Inhalt dieser Datei wird nur von der Kommandozeile verwendet, die ihn in die HELP.md-Datei einfügt.
Die Anweisungen sollten kurz und auf den Punkt sein.
Du kannst auf Ressourcen wie Gitter-Kanäle, Foren oder Mailinglisten verlinken: alles, was Lernenden weiterhilft, wenn sie nicht mehr weiterkommen.
Die Links in diesem Dokument können sich mit denen in docs/LEARNING.md oder docs/RESOURCES.md überschneiden.
Dieses Dokument sollte nicht auf Exercism-weite (trackunabhängige) Hilfe-Ressourcen verlinken, da diese Ressourcen automatisch in die HELP.md-Datei aufgenommen werden.
Beispiel
# Help
To get help if you're having trouble, you can use one of the following resources:
- [Kotlin Documentation](https://kotlinlang.org/docs/reference/)
- [Kotlin Forums](https://discuss.kotlinlang.org/)
- [Kotlin Slack Channel](https://kotlinlang.slack.com/): [get invite here](https://slack.kotlinlang.org/)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlin)
- [Kotlin Subreddit](https://www.reddit.com/r/kotlin)
Datei: representations.md
Zweck: Erklärt, welche Normalisierungen auf eine Lösung angewendet werden, um ihre Repräsentation zu erstellen
Vorkommen: Optional
Wenn ein Track einen Representer implementiert hat, wird für jede eingereichte Lösung eine Repräsentation erstellt.
Dieses Dokument sollte alle Normalisierungen auflisten, die der Representer auf eine Lösung anwendet.
Das hilft einem Mentor, wenn er Kommentare zur Repräsentation hinzufügt.
Beispiel
# Representations
The representer applies the following normalizations:
- All comments are removed
- All import declarations are removed
- The code is formatted
- Identifiers are normalized to a placeholder value
Wenn dein Track eine Datei docs/REPRESENTER_NORMALIZATIONS.md hat, empfehlen wir, die Normalisierungen mit dem entsprechenden Abschnitt in dieser Datei zu verlinken.
Datei: tests.md
Zweck: Enthält trackspezifische Anweisungen, wie man die Tests ausführt
Vorkommen: Erforderlich
Beschreibe, wie man die Tests für diese konkrete Übung ausführt.
Der Inhalt dieser Datei wird nur von der Kommandozeile verwendet, die ihn in die HELP.md-Datei einfügt.
Die Anweisungen sollten kurz und auf den Punkt sein.
Die Datei docs/TESTS.md kann eine ausführlichere Beschreibung enthalten, wie man Tests ausführt.
Beispiel
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Überschreiben
Hinweis: Das ist noch nicht implementiert.
Übungen können die trackspezifischen Dateien überschreiben, indem sie eine gleichnamige Datei im .docs-Verzeichnis der Übung anlegen (z. B. .docs/debug.md). Das sollte nur selten nötig sein (wenn überhaupt).
