Πώς να Συνεισφέρετε στην Τεκμηρίωση

Η συνεισφορά στην τεκμηρίωση είναι μία από τις πιο ωφέλιμες δραστηριότητες, καθώς βοηθάτε άλλους να κατανοήσουν το framework.

Πώς να Γράφετε;

Η τεκμηρίωση προορίζεται κυρίως για άτομα που εξοικειώνονται με το θέμα. Επομένως, θα πρέπει να πληροί αρκετά σημαντικά σημεία:

  • Ξεκινήστε από το απλό και το γενικό. Προχωρήστε σε πιο προχωρημένα θέματα μόνο στο τέλος.
  • Προσπαθήστε να εξηγήσετε το θέμα όσο το δυνατόν καλύτερα. Δοκιμάστε, για παράδειγμα, να εξηγήσετε πρώτα το θέμα σε έναν συνάδελφο.
  • Αναφέρετε μόνο τις πληροφορίες που ο χρήστης πραγματικά χρειάζεται να γνωρίζει για το συγκεκριμένο θέμα.
  • Επαληθεύστε ότι οι πληροφορίες σας είναι όντως αληθείς. Δοκιμάστε κάθε κώδικα.
  • Να είστε συνοπτικοί – ό,τι γράψετε, συντομεύστε το στο μισό. Και μετά, αν θέλετε, ξανά.
  • Χρησιμοποιήστε με φειδώ τα στοιχεία έμφασης κάθε είδους, από έντονα γράμματα μέχρι πλαίσια όπως .[note].
  • Στον κώδικα, τηρήστε τα Πρότυπα Κωδικοποίησης.

Εξοικειωθείτε επίσης με τη σύνταξη. Για προεπισκόπηση του άρθρου κατά τη συγγραφή του, μπορείτε να χρησιμοποιήσετε τον επεξεργαστή με προεπισκόπηση.

Γλωσσικές Εκδόσεις

Η κύρια γλώσσα είναι τα Αγγλικά. Οι αλλαγές σας θα πρέπει ιδανικά να γίνονται και στα Αγγλικά. Αν τα Αγγλικά δεν είναι το δυνατό σας σημείο, χρησιμοποιήστε τον DeepL Translator και οι άλλοι θα ελέγξουν το κείμενό σας.

Η μετάφραση στις άλλες γλώσσες θα γίνει αυτόματα μετά την έγκριση και την τελειοποίηση της τροποποίησής σας.

Ασήμαντες Τροποποιήσεις

Για να συνεισφέρετε στην τεκμηρίωση, είναι απαραίτητο να έχετε λογαριασμό στο GitHub.

Ο ευκολότερος τρόπος για να κάνετε μια μικρή αλλαγή στην τεκμηρίωση είναι να χρησιμοποιήσετε τους συνδέσμους στο τέλος κάθε σελίδας:

  • Το Εμφάνιση στο GitHub ανοίγει την πηγαία μορφή της συγκεκριμένης σελίδας στο GitHub. Στη συνέχεια, αρκεί να πατήσετε το κουμπί E και μπορείτε να αρχίσετε την επεξεργασία (πρέπει να είστε συνδεδεμένοι στο GitHub).
  • Το Άνοιγμα προεπισκόπησης ανοίγει τον επεξεργαστή, όπου βλέπετε αμέσως και την τελική οπτική μορφή.

Επειδή ο επεξεργαστής με προεπισκόπηση δεν έχει τη δυνατότητα αποθήκευσης αλλαγών απευθείας στο GitHub, είναι απαραίτητο μετά την ολοκλήρωση των τροποποιήσεων να αντιγράψετε το πηγαίο κείμενο στο πρόχειρο (με το κουμπί Copy to clipboard) και στη συνέχεια να το επικολλήσετε στον επεξεργαστή στο GitHub. Κάτω από το πεδίο επεξεργασίας υπάρχει μια φόρμα για την υποβολή. Εδώ μην ξεχάσετε να συνοψίσετε και να εξηγήσετε σύντομα τον λόγο της τροποποίησής σας. Μετά την υποβολή δημιουργείται ένα λεγόμενο pull request (PR), το οποίο μπορεί να επεξεργαστεί περαιτέρω.

Μεγαλύτερες Τροποποιήσεις

Πιο κατάλληλο από τη χρήση της διεπαφής του GitHub, είναι να είστε εξοικειωμένοι με τα βασικά της εργασίας με το σύστημα ελέγχου εκδόσεων Git. Αν δεν γνωρίζετε πώς να χρησιμοποιείτε το Git, μπορείτε να δείτε τον οδηγό git – the simple guide και ενδεχομένως να χρησιμοποιήσετε έναν από τους πολλούς γραφικούς clients.

Τροποποιήστε την τεκμηρίωση με αυτόν τον τρόπο:

  1. Στο GitHub, δημιουργήστε ένα fork του αποθετηρίου nette/docs.
  2. Κλωνοποιήστε αυτό το αποθετήριο στον υπολογιστή σας.
  3. Στη συνέχεια, στον κατάλληλο κλάδο πραγματοποιήστε τις αλλαγές.
  4. Ελέγξτε για περιττά κενά στο κείμενο χρησιμοποιώντας το εργαλείο Code-Checker.
  5. Αποθηκεύστε τις αλλαγές (commit).
  6. Αν είστε ικανοποιημένοι με τις αλλαγές, στείλτε (push) τις στο GitHub στο δικό σας fork.
  7. Από εκεί, υποβάλετέ τις στο αποθετήριο nette/docs δημιουργώντας ένα pull request (PR).

Είναι σύνηθες να λαμβάνετε σχόλια με παρατηρήσεις. Παρακολουθήστε τις προτεινόμενες αλλαγές και ενσωματώστε τις. Προσθέστε τις προτεινόμενες αλλαγές ως νέα commits και στείλτε τις ξανά στο GitHub. Ποτέ μην δημιουργείτε νέο pull request για την τροποποίηση ενός υπάρχοντος pull request.

Δομή της Τεκμηρίωσης

Ολόκληρη η τεκμηρίωση βρίσκεται στο GitHub στο αποθετήριο nette/docs. Η τρέχουσα έκδοση βρίσκεται στον κλάδο master, ενώ οι παλαιότερες εκδόσεις βρίσκονται σε κλάδους όπως doc-3.x, doc-2.x.

Το περιεχόμενο κάθε κλάδου χωρίζεται σε κύριους φακέλους που αντιπροσωπεύουν τις επιμέρους ενότητες της τεκμηρίωσης. Για παράδειγμα, το application/ αντιστοιχεί στο https://doc.nette.org/cs/application, το latte/ αντιστοιχεί στο https://latte.nette.org κ.λπ. Κάθε τέτοιος φάκελος περιέχει υποφακέλους που αντιπροσωπεύουν τις γλωσσικές εκδόσεις (cs, en, …) και ενδεχομένως τον υποφάκελο files με εικόνες, τις οποίες είναι δυνατόν να εισαγάγετε στις σελίδες της τεκμηρίωσης.

  1. Τεκμηρίωση
  2. Γίνετε συνεισφέρων στο Nette
  3. Πώς να Συνεισφέρετε στην Τεκμηρίωση