Κάποια αρχεία τεκμηρίωσης ισχύουν και για τις Ασκήσεις Εννοιών και για τις Ασκήσεις Πρακτικής. Αυτά τα αρχεία που μοιράζονται οι ασκήσεις βρίσκονται μέσα στον κατάλογο exercises/shared/.docs της διαδρομής:
-
debug.md: εξηγεί πώς ένας μαθητής που προγραμματίζει στον περιηγητή μπορεί παρ' όλα αυτά να κάνει "debugging" (προαιρετικό)
-
help.md: περιέχει οδηγίες ειδικές για τη διαδρομή σχετικά με το πώς μπορείς να βρεις βοήθεια (υποχρεωτικό)
-
representations.md: εξηγεί ποιες κανονικοποιήσεις εφαρμόζονται σε μια λύση για να δημιουργηθεί η αναπαράστασή της (προαιρετικό)
-
tests.md: περιέχει οδηγίες ειδικές για τη διαδρομή σχετικά με το πώς να τρέχεις τα tests (υποχρεωτικό)
Το έγγραφο Παρουσίασης περιγράφει πώς χρησιμοποιούνται αυτά τα αρχεία για να παρουσιαστεί περιεχόμενο στον μαθητή.
Αρχείο: debug.md
Σκοπός: Να εξηγήσει πώς ένας μαθητής που προγραμματίζει στον περιηγητή μπορεί παρ' όλα αυτά να κάνει "debugging"
Παρουσία: Προαιρετική
Ο editor μέσα στον περιηγητή δεν έχει καμία ενσωματωμένη υποστήριξη για debugging. Αν το test runner της διαδρομής υποστηρίζει την καταγραφή της εξόδου της κονσόλας, ο μαθητής μπορεί παρ' όλα αυτά να κάνει κάποια μορφή "debugging" και αυτό το έγγραφο εξηγεί πώς να το κάνει.
Τα περιεχόμενα αυτού του αρχείου εμφανίζονται μόνο στον online editor, ενώ η γραμμή εντολών θα αγνοήσει αυτό το αρχείο.
Παράδειγμα
# 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");
```
Αρχείο: help.md
Σκοπός: Να εξηγήσει πώς ένας μαθητής μπορεί να βρει βοήθεια
Παρουσία: Υποχρεωτική
Περιγράψε πώς ένας μαθητής μπορεί να βρει βοήθεια, ειδικά για αυτή τη διαδρομή (όχι για όλο το Exercism).
Τα περιεχόμενα αυτού του αρχείου χρησιμοποιούνται μόνο από τη γραμμή εντολών, η οποία το συμπεριλαμβάνει στο αρχείο HELP.md.
Οι οδηγίες πρέπει να είναι σύντομες και περιεκτικές.
Μπορείς να παραπέμψεις σε πόρους όπως κανάλια Gitter, φόρουμ ή λίστες αλληλογραφίας: ό,τι μπορεί να βοηθήσει έναν μαθητή να ξεκολλήσει.
Οι σύνδεσμοι σε αυτό το έγγραφο μπορεί να επικαλύπτονται με αυτούς στα docs/LEARNING.md ή docs/RESOURCES.md.
Αυτό το έγγραφο δεν πρέπει να παραπέμπει σε πόρους βοήθειας για όλο το Exercism (ανεξάρτητους από τη διαδρομή), καθώς αυτοί οι πόροι θα συμπεριληφθούν αυτόματα στο αρχείο HELP.md.
Παράδειγμα
# 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)
Αρχείο: representations.md
Σκοπός: Εξηγεί ποιες κανονικοποιήσεις εφαρμόζονται σε μια λύση για να δημιουργηθεί η αναπαράστασή της
Παρουσία: Προαιρετική
Όταν μια διαδρομή έχει υλοποιήσει έναν representer, για κάθε λύση που υποβάλλεται θα δημιουργείται μια αναπαράσταση.
Αυτό το έγγραφο πρέπει να απαριθμεί όλες τις κανονικοποιήσεις που εφαρμόζει ο representer σε μια λύση.
Αυτό βοηθάει τον μέντορα όταν προσθέτει σχόλια αναπαράστασης.
Παράδειγμα
# 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
Αν η διαδρομή σου έχει ένα αρχείο docs/REPRESENTER_NORMALIZATIONS.md, προτείνουμε να συνδέσεις τις κανονικοποιήσεις με την αντίστοιχη ενότητα σε αυτό το αρχείο.
Αρχείο: tests.md
Σκοπός: Περιέχει οδηγίες ειδικές για τη διαδρομή σχετικά με το πώς να τρέχεις τα tests
Παρουσία: Υποχρεωτική
Περιγράψε πώς να τρέχεις τα tests για τη συγκεκριμένη άσκηση.
Τα περιεχόμενα αυτού του αρχείου χρησιμοποιούνται μόνο από τη γραμμή εντολών, η οποία το συμπεριλαμβάνει στο αρχείο HELP.md.
Οι οδηγίες πρέπει να είναι σύντομες και περιεκτικές.
Το αρχείο docs/TESTS.md μπορεί να περιέχει μια πιο αναλυτική περιγραφή για το πώς να τρέχεις τα tests.
Παράδειγμα
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Αντικατάσταση
Σημείωση: αυτό δεν έχει υλοποιηθεί ακόμη
Οι ασκήσεις μπορούν να αντικαταστήσουν τα αρχεία που είναι ειδικά για τη διαδρομή δημιουργώντας ένα αρχείο με το ίδιο όνομα στον κατάλογο .docs της άσκησης (π.χ. .docs/debug.md). Αυτό θα χρειάζεται σπάνια (αν χρειάζεται ποτέ).
