Το πρόβλημα με τη wiki του GitHub
Η wiki είναι διαθέσιμη με ένα κλικ από οπουδήποτε στο αποθετήριο, αλλά αυτό είναι το μοναδικό της πλεονέκτημα. Δεν υποστηρίζει versioning junto με τον κώδικα, δεν είναι διαθέσιμη τοπικά όταν κλώνετε το αποθετήριο (μπορείτε να κλώνετε τη ξεχωριστά, αλλά αυτό είναι λίγο γνωστό), και δεν επιτρέπει εύκολη εικόνα upload – χρειάζεστε εξωτερικό χώρο για εικόνες.
Γιατί το /docs folder είναι καλύτερη επιλογή
Αποθηκεύοντας τη τεκμηρία σε φάκελο /docs στο ίδιο branch με τον κώδικα:
- Η τεκμηρία.versioned (versioned) είναι, οπότε μπορείτε να την δείτε σε οποιαδήποτε προηγούμενη έκδοση.
- Η τεκμηρία είναι διαθέσιμη τοπικά μετά clone, χωρίς πρόσθετες ενέργειες.
- Οι αλλαγές υποβάλλονται μέσω pull request, λαμβάνοντας τον ίδιο έλεγχο κώδικα.
- Μπορείτε να ενσωματώσετε CI pipelines για linting (π.χ. Vale) και spell‑checking με εργαλεία που γνωρίζετε (π.χ. VS Code).
Ρύθμιση δημοσίευσης με GitHub Pages
- Τοποθετήστε τα αρχεία τεκμηριώσης στον φάκελο /docs.
- Ενεργοποιήστε GitHub Pages να δημιουργεί το site από τον φάκελο /docs (μπορείτε να χρησιμοποιήσετε το θέμα just‑the‑docs ή το δικό σας workflow με Hugo και την corresponding GitHub Action).
- Προσθέστε μια μόνο σελίδα στην wiki που οδηγεί χρήστες στο δημοσιευμένο site, ώστε να υπάρχει η «one‑click» πρόσβαση χωρίς να θυσιάζετε τα πλεονεκτήματα του versioned docs.
Μελλοντική εξέλιξη
Όταν η τεκμηρία fuera fuera από έναν απλό φάκελο, η μεταφορά σε ξεχωριστό αποθετήριο με δική της διαδικασία build και pull‑review είναι απλή, επειδή οι συνεργάτες έχουν ήδη συνetheia με την τεκμηρία σε αποθετήριο. Έτσι η μετανάστευση είναι ομαλή και δεν διαταράσσει την ροę εργασίας.