Alcuni file di documentazione si applicano sia agli esercizi concettuali sia agli esercizi di pratica. Questi file trasversali agli esercizi si trovano nella directory exercises/shared/.docs del track:
-
debug.md: spiega come uno studente che programma nel browser possa 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)
Il documento di presentazione descrive come questi file vengono usati per presentare i contenuti allo studente.
File: debug.md
Scopo: spiegare come uno studente che programma nel browser possa comunque fare «debugging»
Presenza: opzionale
L'editor nel browser non ha alcun supporto integrato per il debugging. Se il test runner del track supporta la cattura dell'output della console, lo studente può comunque fare una qualche forma di «debugging», e questo documento spiega come.
Il contenuto di questo file viene mostrato solo nell'editor online; la CLI ignorerà questo file.
Esempio
# 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");
```
File: help.md
Scopo: spiegare come uno studente può ottenere aiuto
Presenza: obbligatorio
Descrivi come uno studente può ottenere aiuto, specificamente per questo track (non per tutto Exercism).
Il contenuto di questo file viene usato solo dalla CLI, che lo include nel file HELP.md.
Le istruzioni dovrebbero essere brevi e dirette.
Puoi aggiungere link a risorse come canali Gitter, forum o mailing list: qualsiasi cosa che possa aiutare uno studente a sbloccarsi.
I link in questo documento possono sovrapporsi a quelli in docs/LEARNING.md o docs/RESOURCES.md.
Questo documento non dovrebbe rimandare a risorse di aiuto valide per tutto Exercism (indipendenti dal track), perché quelle risorse verranno incluse automaticamente nel file HELP.md.
Esempio
# 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)
File: representations.md
Scopo: spiega quali normalizzazioni vengono applicate a una soluzione per creare la sua rappresentazione
Presenza: opzionale
Quando un track ha implementato un representer, per ogni soluzione inviata viene creata una rappresentazione.
Questo documento dovrebbe elencare tutte le normalizzazioni che il representer applica a una soluzione.
Questo aiuta un mentore quando aggiunge commenti sulla rappresentazione.
Esempio
# 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
Se il track ha un file docs/REPRESENTER_NORMALIZATIONS.md, ti consigliamo di collegare le normalizzazioni alla sezione corrispondente di quel file.
File: tests.md
Scopo: contiene istruzioni specifiche del track su come eseguire i test
Presenza: obbligatorio
Descrivi come eseguire i test per questo particolare esercizio.
Il contenuto di questo file viene usato solo dalla CLI, che lo include nel file HELP.md.
Le istruzioni dovrebbero essere brevi e dirette.
Il file docs/TESTS.md può contenere una descrizione più dettagliata di come eseguire i test.
Esempio
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Sovrascrittura
Nota: non è ancora implementato
Gli esercizi possono sovrascrivere i file specifici del track creando un file con lo stesso nome nella directory .docs dell'esercizio (ad esempio .docs/debug.md). Dovrebbe servire solo raramente (se mai).
