Präsentation

Dieses Dokument beschreibt, wie die verschiedenen Übungs- und Track-Dateien dem Lernenden präsentiert werden, wobei berücksichtigt wird, ob der Lernende die Kommandozeile oder den Editor verwendet.

Dokumentation

Es gibt drei Arten von Dokumentation, die bestimmen, welche Dokumentation für eine Übung präsentiert wird.

Übungsspezifische Dateien

Diese Dateien sind für jede Übung spezifisch:

  • .docs/introduction.md: führt die Konzepte ein, die die Übung dem Lernenden vermittelt (erforderlich)
  • .docs/introduction.append.md: zusätzlicher Einleitungstext, der nach der bestehenden Einleitung angehängt wird (wird in Konzeptübungen nicht verwendet, optional für Praxisübungen)
  • .docs/instructions.md: liefert die Anleitung für die Übung (erforderlich)
  • .docs/instructions.append.md: zusätzlicher Einleitungstext, der nach der bestehenden Anleitung angehängt wird (wird in Konzeptübungen nicht verwendet, optional für Praxisübungen)
  • .docs/hints.md: gibt dem Lernenden Hinweise, damit er bei einer Übung wieder weiterkommt (erforderlich für Konzeptübungen, optional für Praxisübungen)
  • .meta/config.json: enthält Quellenangaben zur Übung (optional)

Weitere Informationen findest du in der Dokumentation zu den Konzeptübungen und der Dokumentation zu den Praxisübungen.

Trackspezifische Dateien

Diese Dateien sind allen Übungen gemeinsam:

  • debug.md: erklärt, wie ein Lernender, der im Browser programmiert, trotzdem „debuggen“ kann (optional)
  • help.md: enthält trackspezifische Anleitungen, wie man Hilfe bekommt (erforderlich)
  • representations.md: erklärt, welche Normalisierungen auf eine Lösung angewendet werden, um ihre Repräsentation zu erzeugen (optional)
  • tests.md: enthält trackspezifische Anleitungen, wie man die Tests ausführt (erforderlich)

Weitere Informationen findest du in der Dokumentation zu den gemeinsamen Dateien.

Exercism-weite Dokumentation

Neben den oben genannten track- bzw. übungsspezifischen Dokumentationsdateien gibt es zwei Teile der Dokumentation, die Exercism-weit gelten (und daher von allen Tracks geteilt werden):

  • Anleitungen, wie man die Kommandozeile benutzt, um eine Übung einzureichen
  • Anleitungen, wie man Hilfe bekommt

Editor

Wenn ein Lernender eine Übung im Browser bearbeitet, werden die Dokumentationsdateien zu den passenden Zeitpunkten angezeigt. Hinweise werden zum Beispiel nur dann angezeigt, wenn der Lernende sie anfordert. Der Editor muss auch keine Anleitungen zur Kommandozeile anzeigen.

Kommandozeile

Wenn du lokal über die Kommandozeile arbeitest, haben wir nicht die Möglichkeit, Dokumentation bedingt anzuzeigen. Deshalb muss die Kommandozeile immer die gesamte relevante Dokumentation herunterladen. Damit der Lernende nicht mehrere Dateien öffnen muss, fügt die Kommandozeile die gesamte relevante Dokumentation zu drei Dokumenten zusammen:

README.md

Diese Datei enthält die Anleitung der Übung, die Einleitung (optional) und die Quellenangaben (optional).

# [exercise name]

Welcome to [exercise name] on Exercism's [track name] Track.
If you need help running the tests or submitting your code, check out `HELP.md`.
If you get stuck on the exercise, check out `HINTS.md`, but try and solve it without using those first :)

## Introduction (optional)

[Exercise-specific file: .docs/introduction.md] (optional)

[Exercise-specific file: .docs/introduction.append.md] (optional)

## Instructions

[Exercise-specific file: .docs/instructions.md]

[Exercise-specific file: .docs/instructions.append.md] (optional)

## Source

### Created by

- @[author-1 handle]
- @[author-2 handle]
  ...

### Contributed to by (optional)

- @[contributor-1 handle]
- @[contributor-2 handle]
  ...

### Based on

[source] - [source url]

HELP.md

Diese Datei beschreibt, wie man die Tests ausführt, sowie trackspezifische und Exercism-weite Anleitungen zur Hilfe.

# Help

## Running the tests

[Track-specific file: exercises/shared/.docs/tests.md]

## Submitting your solution

[Exercism-wide documentation: instructions on how to submit a solution]

## Need to get help?

[Exercism-wide documentation: instructions on how to get help]

[Track-specific file: exercises/shared/.docs/help.md]

HINTS.md

Diese Datei enthält die übungsspezifischen Hinweise (optional)

# Hints

## General

- Consider extracting the logic to a helper function.