Presentazione

Questo documento descrive come i vari file degli esercizi e dei track vengono presentati allo studente, a seconda che lo studente usi la CLI o l'editor.

Documentazione

Ci sono tre tipi di documentazione che determinano quale documentazione viene presentata per un esercizio.

File specifici dell'esercizio

Questi file sono specifici di ogni esercizio:

  • .docs/introduction.md: introduce il concetto (o i concetti) che l'esercizio insegna allo studente (obbligatorio)
  • .docs/introduction.append.md: testo di introduzione aggiuntivo da accodare dopo l'introduzione esistente (non usato negli esercizi concettuali, opzionale per gli esercizi pratici)
  • .docs/instructions.md: fornisce le istruzioni per l'esercizio (obbligatorio)
  • .docs/instructions.append.md: testo di introduzione aggiuntivo da accodare dopo le istruzioni esistenti (non usato negli esercizi concettuali, opzionale per gli esercizi pratici)
  • .docs/hints.md: fornisce suggerimenti allo studente per aiutarlo a sbloccarsi in un esercizio (obbligatorio per gli esercizi concettuali, opzionale per gli esercizi pratici)
  • .meta/config.json: contiene le informazioni sulla fonte dell'esercizio (opzionale)

Per maggiori informazioni, consulta la documentazione sugli esercizi concettuali e la documentazione sugli esercizi pratici.

File specifici del track

Questi file sono condivisi tra tutti gli esercizi:

  • debug.md: spiega come uno studente che programma nel browser può comunque fare «debugging» (opzionale)
  • help.md: contiene istruzioni specifiche del track su come ottenere aiuto (obbligatorio)
  • representations.md: spiega quali normalizzazioni vengono applicate a una soluzione per creare la sua rappresentazione (opzionale)
  • tests.md: contiene istruzioni specifiche del track su come eseguire i test (obbligatorio)

Per maggiori informazioni, consulta la documentazione sui file condivisi.

Documentazione valida per tutto Exercism

Oltre ai file di documentazione specifici del track o dell'esercizio descritti sopra, ci sono due parti di documentazione valide per tutto Exercism (e quindi condivise da tutti i track):

  • Istruzioni su come usare la CLI per inviare un esercizio
  • Istruzioni su come ottenere aiuto

Editor

Quando si lavora a un esercizio nel browser, i file di documentazione vengono mostrati al momento opportuno. Per esempio, i suggerimenti non vengono mostrati a meno che lo studente non ne richieda la visualizzazione. Inoltre, l'editor non ha bisogno di mostrare le istruzioni per la CLI.

CLI

Quando si lavora in locale tramite la CLI, non abbiamo la possibilità di mostrare la documentazione in modo condizionale. Perciò la CLI deve sempre scaricare tutta la documentazione pertinente. Per non costringere lo studente ad aprire diversi file, la CLI concatena tutta la documentazione pertinente in tre documenti:

README.md

Questo file contiene le istruzioni dell'esercizio, l'introduzione (opzionale) e le informazioni sulla fonte (opzionale).

# [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

Questo file descrive come eseguire i test e fornisce istruzioni di aiuto specifiche del track e valide per tutto Exercism.

# 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

Questo file contiene i suggerimenti specifici dell'esercizio (opzionale)

# Hints

## General

- Consider extracting the logic to a helper function.