Αυτό το έγγραφο περιγράφει πώς παρουσιάζονται στον μαθητή τα διάφορα αρχεία ασκήσεων και διαδρομών, λαμβάνοντας υπόψη αν ο μαθητής χρησιμοποιεί το CLI ή τον editor.
Τεκμηρίωση
Υπάρχουν τρεις τύποι τεκμηρίωσης που καθορίζουν ποια τεκμηρίωση παρουσιάζεται για μια άσκηση.
Αρχεία ειδικά για την άσκηση
Αυτά τα αρχεία είναι ειδικά για κάθε άσκηση:
-
.docs/introduction.md: παρουσιάζει στον μαθητή την έννοια ή τις έννοιες που διδάσκει η άσκηση (απαιτείται)
-
.docs/introduction.append.md: πρόσθετο κείμενο εισαγωγής που προσαρτάται μετά την υπάρχουσα εισαγωγή (δεν χρησιμοποιείται σε ασκήσεις εννοιών, προαιρετικό για ασκήσεις πρακτικής)
-
.docs/instructions.md: παρέχει τις οδηγίες της άσκησης (απαιτείται)
-
.docs/instructions.append.md: πρόσθετο κείμενο οδηγιών που προσαρτάται μετά τις υπάρχουσες οδηγίες (δεν χρησιμοποιείται σε ασκήσεις εννοιών, προαιρετικό για ασκήσεις πρακτικής)
-
.docs/hints.md: παρέχει υποδείξεις στον μαθητή για να τον βοηθήσει να ξεκολλήσει σε μια άσκηση (απαιτείται για τις ασκήσεις εννοιών, προαιρετικό για τις ασκήσεις πρακτικής)
-
.meta/config.json: περιέχει πληροφορίες προέλευσης της άσκησης (προαιρετικό)
Δες την τεκμηρίωση των ασκήσεων εννοιών και την τεκμηρίωση των ασκήσεων πρακτικής για περισσότερες πληροφορίες.
Αρχεία ειδικά για τη διαδρομή
Αυτά τα αρχεία είναι κοινά για όλες τις ασκήσεις:
-
debug.md: εξηγεί πώς ένας μαθητής που γράφει κώδικα στον browser μπορεί να κάνει ακόμα και "debugging" (προαιρετικό)
-
help.md: περιέχει οδηγίες ειδικές για τη διαδρομή σχετικά με το πώς να βρεις βοήθεια (απαιτείται)
-
representations.md: εξηγεί ποιες κανονικοποιήσεις εφαρμόζονται σε μια λύση για να δημιουργηθεί η αναπαράστασή της (προαιρετικό)
-
tests.md: περιέχει οδηγίες ειδικές για τη διαδρομή σχετικά με το πώς να τρέξεις τα tests (απαιτείται)
Δες την τεκμηρίωση των κοινών αρχείων για περισσότερες πληροφορίες.
Τεκμηρίωση για όλο το Exercism
Εκτός από τα παραπάνω αρχεία τεκμηρίωσης, που είναι ειδικά για τη διαδρομή ή την άσκηση, υπάρχουν δύο κομμάτια τεκμηρίωσης που ισχύουν για όλο το Exercism (και άρα είναι κοινά σε όλες τις διαδρομές):
- Οδηγίες για το πώς να χρησιμοποιήσεις το CLI για να υποβάλεις μια άσκηση
- Οδηγίες για το πώς να βρεις βοήθεια
Ο editor
Όταν δουλεύεις μια άσκηση στον browser, τα αρχεία τεκμηρίωσης εμφανίζονται την κατάλληλη στιγμή. Για παράδειγμα, οι υποδείξεις δεν εμφανίζονται αν ο μαθητής δε ζητήσει να του εμφανιστούν. Ο editor, επίσης, δε χρειάζεται να εμφανίζει τις οδηγίες του CLI.
CLI
Όταν δουλεύεις τοπικά μέσω του CLI, δεν υπάρχει η δυνατότητα να εμφανίζεται η τεκμηρίωση υπό συνθήκες. Γι' αυτό, το CLI πρέπει πάντα να κατεβάζει όλη τη σχετική τεκμηρίωση. Για να μη χρειάζεται ο μαθητής να ανοίξει πολλά αρχεία, το CLI συνενώνει όλη τη σχετική τεκμηρίωση σε τρία έγγραφα:
README.md
Αυτό το αρχείο περιέχει τις οδηγίες της άσκησης, την εισαγωγή (προαιρετικά) και τις πληροφορίες προέλευσης (προαιρετικά).
# [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
Αυτό το αρχείο περιγράφει πώς να τρέξεις τα tests, καθώς και οδηγίες βοήθειας για τη διαδρομή και για όλο το 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
Αυτό το αρχείο περιέχει τις υποδείξεις που είναι ειδικές για την άσκηση (προαιρετικό)
# Hints
## General
- Consider extracting the logic to a helper function.
