Εάν δύο αποθετήρια GitHub περιέχουν ακριβώς τον ίδιο κώδικα, αλλά μόνο το ένα έχει ένα καλογραμμένο και οπτικά ελκυστικό αρχείο README , σχεδόν όλοι θα επιλέξουν το δεύτερο. Σε ένα περιβάλλον όπως το GitHub, όπου χιλιάδες έργα ανταγωνίζονται για την προσοχή, το αρχείο README είναι η επαγγελματική σας κάρτα, η βιτρίνα σας και συχνά η διαφορά μεταξύ του να δοκιμάσει κάποιος το έργο σας ή να το κλείσει μετά από δύο δευτερόλεπτα.
Ένα README δεν είναι απλώς μια τυπική διαδικασία: είναι το μέρος όπου εξηγείτε τι έχετε δημιουργήσει, γιατί υπάρχει, πώς να το χρησιμοποιήσετε και τι το κάνει ξεχωριστό . Λέει επίσης πολλά για εσάς ως προγραμματιστή: τις επικοινωνιακές σας δεξιότητες, την προσοχή σας στη λεπτομέρεια και τον επαγγελματισμό σας. Ας δούμε, βήμα προς βήμα, τι πρέπει να περιλαμβάνει ένα README για να κάνει το έργο σας να ξεχωρίζει πραγματικά στο GitHub και πώς να αξιοποιήσετε όλες τις δυνατότητές του.
Τι είναι ένα README και γιατί έχει τόσο μεγάλο βάρος στο GitHub;
Το README είναι ένα αρχείο κειμένου σε μορφή Markdown, που συνήθως ονομάζεται README.md, το οποίο δείχνει το GitHub από προεπιλογή στην κύρια σελίδα του αποθετηρίουΕίναι το πρώτο πράγμα που βλέπει κάποιος όταν μπαίνει, επομένως λειτουργεί ως εξώφυλλο, συνοπτική παρουσίαση και βασικό εγχειρίδιο του έργου σας, όλα σε ένα.
Από τεχνικής άποψης, το Markdown είναι μια πολύ απλή γλώσσα σήμανσης που μεταφράζεται σε HTML . Αυτό σας επιτρέπει να προσθέτετε επικεφαλίδες, λίστες, συνδέσμους, εικόνες, πίνακες, αποσπάσματα κώδικα ή emoji χωρίς καμία ταλαιπωρία. Επιπλέον, το GitHub ερμηνεύει αυτόματα αυτό το Markdown, έτσι ώστε με ένα μόνο αρχείο απλού κειμένου, να μπορείτε να επιτύχετε μια κομψή παρουσίαση.
Ένα καλογραμμένο README απαντά με σαφήνεια σε τρία βασικά ερωτήματα: τι κάνει το έργο σας, πώς χρησιμοποιείται και γιατί θα πρέπει να ενδιαφέρει κάποιον . Αν κάποιος πρέπει να το αποκρυπτογραφήσει κοιτάζοντας το δέντρο αρχείων ή διαβάζοντας κώδικα χωρίς συμφραζόμενα, πιθανότατα θα ανατρέξει σε ένα καλύτερα τεκμηριωμένο αποθετήριο.
Επιπλέον, πολλοί προγραμματιστές και recruiters χρησιμοποιούν το GitHub ως επαγγελματικό χαρτοφυλάκιο . Εάν συναντήσουν αποθετήρια γεμάτα με κώδικα αλλά χωρίς αρχεία README ή με ελάχιστες περιγραφές, πιθανότατα θα υποθέσουν ότι το έργο είναι ακατέργαστο ή ότι δεν σας ενδιαφέρει η τεκμηρίωση. Αντίθετα, τα πολλαπλά αποθετήρια με ισχυρά αρχεία README μεταδίδουν επαγγελματισμό, προσοχή στη λεπτομέρεια και την ικανότητα αποτελεσματικής συνεργασίας.
Υπάρχουν επίσης περιπτώσεις όπου δεν ενδιαφέρεστε να προσελκύσετε χρήστες ή συνεισφέροντες, για παράδειγμα, εάν πρόκειται για εσωτερικό αποθετήριο ή για προσωπικό πείραμα. Σε αυτές τις περιπτώσεις, ένα πλήρες README μπορεί να μην είναι τόσο απαραίτητο. Γενικά, όμως, εάν το αποθετήριο είναι δημόσιο και αποτελεί μέρος της εικόνας σας ως προγραμματιστή, η επένδυση χρόνου στο README δεν είναι σχεδόν ποτέ λάθος.
Βασικά στοιχεία που δεν μπορούν να λείπουν από ένα README που ξεχωρίζει
Αν κοιτάξετε δημοφιλή έργα στο GitHub, θα δείτε ότι τα αρχεία README τους μπορεί να έχουν πολύ διαφορετικά στυλ, αλλά συνήθως μοιράζονται μια σειρά από κοινές ενότητες και πόρους . Το Docusaurus, το Open MCT της NASA, μεγάλα SDK όπως αυτά από το Dropbox ή τα εργαλεία του Facebook είναι καλά παραδείγματα: το καθένα έχει τη δική του προσωπικότητα, αλλά όλα χειρίζονται πολύ καλά την πτυχή της παρουσίασης.
Η ιδέα δεν είναι να αντιγράψετε ακριβώς ένα μοτίβο, αλλά να κατανοήσετε ποια στοιχεία είναι χρήσιμα και να τα προσαρμόσετε στο έργο σας και στο κοινό-στόχο σας . Με βάση τα καλύτερα παραδείγματα και τις προτάσεις από διάφορους οδηγούς, μπορούμε να προσδιορίσουμε ένα σύνολο βασικών στοιχείων που πρέπει να έχετε κατά νου κατά την προετοιμασία του README σας.
Ως γενικός οδηγός, ένα πλήρες αρχείο README συνήθως περιλαμβάνει έναν ελκυστικό τίτλο, μια εικόνα ή λογότυπο, σήματα, έναν πίνακα περιεχομένων, μια περιγραφή, την κατάσταση του έργου, οδηγίες εγκατάστασης, οδηγίες χρήσης, μια επίδειξη, τεχνολογίες, συνεισφέροντες, συγγραφείς, μια άδεια χρήσης και, σε ορισμένες περιπτώσεις, επιπλέον ενότητες όπως δοκιμές ή πώς να συνεισφέρετε. Η χρήση όλων αυτών δεν είναι υποχρεωτική, αλλά θα πρέπει να λάβετε υπόψη ποιες είναι πιο κατάλληλες για την περίπτωσή σας.
Το κλειδί είναι να βρεθεί η σωστή ισορροπία: αρκετά λεπτομερές ώστε ο καθένας να μπορεί να κατανοήσει και να χρησιμοποιήσει το έργο σας , αλλά χωρίς να μετατρέψει το README σε έναν ατελείωτο τοίχο κειμένου. Για πιο τεχνικό και εκτενές περιεχόμενο, μπορείτε πάντα να συνδεθείτε με εξωτερική τεκμηρίωση.
Λάβετε επίσης υπόψη ότι το GitHub δημιουργεί αυτόματα έναν πίνακα περιεχομένων από τις επικεφαλίδες, στον οποίο έχετε πρόσβαση από ένα εικονίδιο στην επάνω αριστερή γωνία του README, επομένως μια καλή δομή επικεφαλίδων βοηθά σημαντικά στην πλοήγηση, ακόμα κι αν δεν δημιουργήσετε το δικό σας χειροκίνητο ευρετήριο.
Τίτλος, εξώφυλλο και εικόνες στο README
Το πρώτο στοιχείο που εμφανίζεται σε ένα README είναι συνήθως ο τίτλος, τον οποίο το GitHub αρχικοποιεί με το όνομα του αποθετηρίου . Ωστόσο, δεν είστε υποχρεωμένοι να διατηρήσετε ακριβώς αυτό το όνομα: μπορείτε να το αλλάξετε μέσα στο ίδιο το README σε έναν πιο περιγραφικό και φιλικό προς τον χρήστη τίτλο.
Ένας καλός τίτλος συνδυάζει σαφήνεια και ελκυστικότητα: Εξηγήστε τι κάνει το έργο και, αν σας ταιριάζει, προσθέστε μια δημιουργική πινελιά.Στο Markdown, είναι σύνηθες να χρησιμοποιείτε μια επικεφαλίδα ανώτατου επιπέδου, αν και μπορείτε επίσης να χρησιμοποιήσετε μια ετικέτα HTML όπως <h1 align="center"> αν θέλετε να φαίνεται κεντραρισμένο ή δοκιμάστε μικρότερα μεγέθη αν έχετε ήδη ένα κυρίαρχο λογότυπο.
Ακριβώς κάτω από τον τίτλο, είναι καλή ιδέα να συμπεριλάβετε μια εικόνα εξωφύλλου ή ένα λογότυπο έργου . Μπορείτε να το σχεδιάσετε με εργαλεία όπως το Canva ή οποιοδήποτε πρόγραμμα επεξεργασίας προτιμάτε και στη συνέχεια να το προσθέσετε στο README. Στο GitHub, απλώς σύρετε το αρχείο στον επεξεργαστή README και αυτός θα δημιουργήσει αυτόματα την αναφορά εικόνας και θα την ανεβάσει στο αποθετήριο.
Κατά την εισαγωγή εικόνων, είναι σημαντικό να μην αφήσετε την προεπιλεγμένη περιγραφή: Συμπληρώστε το εναλλακτικό κείμενο με κάτι που περιγράφει ελάχιστα αυτό που βλέπετε.Για προσβασιμότητα και για χρήστες που περιηγούνται με προγράμματα ανάγνωσης οθόνης. Εάν προτιμάτε να ελέγχετε μόνοι σας τις διαδρομές, μπορείτε επίσης να ανεβάσετε τις εικόνες σε έναν φάκελο στο αποθετήριο (για παράδειγμα, assets/images) και να τα συνδέσετε χρησιμοποιώντας το συμβατικό Markdown.
Μια άλλη επιλογή είναι να χρησιμοποιήσετε υπηρεσίες φιλοξενίας εικόνων όπως το Imgur ή παρόμοιες, αλλά από άποψη αξιοπιστίας, είναι ασφαλέστερο να διατηρείτε τις εικόνες σας στο δικό σας αποθετήριο . Με αυτόν τον τρόπο, δεν εξαρτάστε από έναν εξωτερικό διακομιστή που διαγράφει ή τροποποιεί το αρχείο και αφήνει το αρχείο README γεμάτο κενά.
Εμβλήματα για την εμφάνιση κατάστασης, στατιστικών στοιχείων και μετρήσεων
Τα badges έχουν γίνει σχεδόν στάνταρ στα σύγχρονα README. Είναι μικρές εικόνες με κείμενο που συνοψίζουν βασικές πληροφορίες έργου με μια ματιά : κατάσταση δοκιμών, τύπος άδειας χρήσης, τρέχουσα έκδοση, χρήση εξαρτήσεων, αριθμός αστεριών, δραστηριότητα Discord κ.λπ.
Πολλά μεγάλα αποθετήρια χρησιμοποιούν αυτά τα σήματα για να παρέχουν γρήγορο περιεχόμενο. Για παράδειγμα, ένα SDK Dropbox μπορεί να εμφανίζει ένα σήμα με την άδεια χρήσης MIT, την υποστηριζόμενη έκδοση Maven και την ημερομηνία της τελευταίας κυκλοφορίας . Αυτού του είδους οι λεπτομέρειες σάς βοηθούν να αξιολογήσετε εάν το έργο είναι ενεργό, το επίπεδο ωριμότητάς του ή εάν ταιριάζει με τη στοίβα σας.
Ο ευκολότερος τρόπος για να δημιουργήσετε badges είναι χρησιμοποιώντας το Shields.io , μια υπηρεσία που δημιουργεί δυναμικές εικόνες από URL. Απλώς επιλέξτε τον τύπο badge, καθορίστε το κείμενο και τα χρώματα ή ακόμα και δώστε τη διεύθυνση URL του αποθετηρίου σας για να προτείνει προδιαμορφωμένα badges. Στη συνέχεια, απλώς επικολλήστε τον σύνδεσμο στο αρχείο README.
Ένα τυπικό παράδειγμα θα ήταν ένα σήμα που υποδεικνύει ότι το έργο βρίσκεται υπό ανάπτυξη, κάτι σαν ένα πράσινο σήμα με την ένδειξη «ΚΑΤΑΣΤΑΣΗ – ΥΠΟ ΑΝΑΠΤΥΞΗ». Μπορείτε επίσης να προσθέσετε ένα κοινωνικό σήμα με τον αριθμό των αστεριών για τον λογαριασμό ή τον οργανισμό σας , που σηματοδοτεί ότι υπάρχει δραστηριότητα στον διακομιστή Discord ή ότι η τεκμηρίωση είναι ενημερωμένη.
Όσον αφορά την παρουσίαση, έχετε την ελευθερία να τα τοποθετήσετε ενσωματωμένα ακριβώς κάτω από τον τίτλο ή σε μια κεντρική παράγραφο χρησιμοποιώντας HTML, για παράδειγμα περικλείοντας πολλές εικόνες σε ένα <p align="center">Το σημαντικό είναι να μην το παρακάνετε: Επιλέξτε τα σήματα που παρέχουν πραγματικά χρήσιμες πληροφορίες και αποφύγετε να γεμίσετε την κεφαλίδα με εικονίδια που κανείς δεν θα διαβάσει.
Πίνακας περιεχομένων και εσωτερική δομή του εγγράφου
Όταν το README σας αρχίσει να γίνεται αρκετά μεγάλο, αξίζει να σκεφτείτε την πλοήγηση. Το GitHub προσφέρει ήδη έναν πίνακα περιεχομένων στην πλαϊνή μπάρα που δημιουργείται αυτόματα από τις επικεφαλίδες Markdown, προσβάσιμος μέσω ενός μικρού εικονιδίου μενού στο επάνω μέρος.
Ακόμα κι έτσι, σε μεγάλα έργα είναι πολύ χρήσιμο να συμπεριληφθεί ένα χειροκίνητο ευρετήριο στην αρχή του αρχείου , με εσωτερικούς συνδέσμους προς κάθε κύρια ενότητα. Με αυτόν τον τρόπο, ο καθένας μπορεί να μεταβεί στην εγκατάσταση, τη χρήση, τις συνεισφορές ή τις άδειες χρήσης με ένα μόνο κλικ, χωρίς να χρειάζεται να κάνει ατελείωτη κύλιση.
Για τη δημιουργία αυτού του ευρετηρίου, χρησιμοποιούνται σύνδεσμοι που παραπέμπουν στα αναγνωριστικά που δημιουργούνται από το GitHub για κάθε τίτλο. Για παράδειγμα, μια ενότητα ## Instalación Συνήθως αναφέρεται ως #instalación στους συνδέσμους. Με μια εσωτερική λίστα συνδέσμων, μπορείτε να δημιουργήσετε ένα μενού τύπου "Πίνακας περιεχομένων" που είναι οικείο στους χρήστες.
Είναι σημαντικό να είστε συνεπείς με τις επικεφαλίδες σας: χρησιμοποιήστε λογικά επίπεδα (h2, h3, κ.λπ.) και ονομάστε τις ενότητές σας με σαφήνεια . Αυτό όχι μόνο βοηθάει με τη χειροκίνητη δημιουργία ευρετηρίου, αλλά και με τον αυτόματο πίνακα που δημιουργείται από το GitHub και τη συνολική αναγνωσιμότητα του εγγράφου.
Εάν το README είναι σύντομο, το ευρετήριο είναι προαιρετικό. Αλλά μετά από έναν ορισμένο αριθμό ενοτήτων γίνεται πολύ πρακτικό, ειδικά εάν δημοσιεύσετε έναν εκτενή οδηγό, ένα API με πολλές ενότητες ή ένα έργο με σύνθετη εγκατάσταση.
Περιγραφή έργου: τι είναι, σε ποιον απευθύνεται και ποιο πρόβλημα λύνει
Η ενότητα περιγραφής είναι ίσως η πιο σημαντική από εννοιολογικής άποψης. Εδώ εξηγείτε, σύντομα αλλά με δυναμικό τρόπο, περί τίνος πρόκειται το έργο σας, γιατί υπάρχει και τι προσφέρει . Δεν χρειάζεται να είναι δοκίμιο, αλλά θα πρέπει να είναι κάτι περισσότερο από μια γενική πρόταση.
Μια βέλτιστη πρακτική είναι να απαντήσετε ρητά σε ορισμένα βασικά ερωτήματα: τι σας παρακίνησε να το δημιουργήσετε, ποιο πρόβλημα λύνει, τι μάθατε κατά την ανάπτυξη και τι κάνει την προσέγγισή σας διαφορετική ; Εάν ο μόνος λόγος είναι «επειδή ήταν μια εργασία τάξης», είναι καλύτερο να εμβαθύνετε λίγο περισσότερο και να μιλήσετε για τις τεχνικές προκλήσεις, τις αποφάσεις σχεδιασμού ή την αξία για ορισμένους χρήστες.
Σε ορισμένα έργα, η περιγραφή είναι πολύ συνοπτική, όπως σε ορισμένα SDK που απλώς εξηγούν ότι παρέχουν μια βιβλιοθήκη για την πρόσβαση σε ένα συγκεκριμένο API και αναφέρουν συμβατότητες . Σε άλλα, ειδικά σε ολοκληρωμένες εφαρμογές ή σύνθετα προϊόντα, παρέχονται περισσότερες λεπτομέρειες, εξηγούνται περιπτώσεις χρήσης και περιλαμβάνονται πραγματικά στοιχεία ή παραδείγματα.
Δοκιμάστε να γράψετε αυτήν την ενότητα έχοντας κατά νου κάποιον που θα ξεκινήσει από την αρχή: αποφύγετε την περιττή ορολογία και εξηγήστε το πλαίσιο με σαφή και κατανοητό τρόπο . Μπορείτε να χρησιμοποιήσετε μία μόνο πρόταση για να συνοψίσετε τον στόχο και μία ή δύο παραγράφους για να προσθέσετε λεπτομέρειες σχετικά με το κοινό-στόχο ή το είδος του προβλήματος που επιλύετε.
Αν έχετε μια λειτουργική ηλεκτρονική επίδειξη, είναι ένα καλό σημείο να αναφέρετε ότι το έργο έχει αναπτυχθεί, να δημιουργήσετε έναν σύνδεσμο προς αυτήν την επίδειξη ή ακόμα και να προσκαλέσετε τον αναγνώστη να τη δοκιμάσει πριν συνεχίσετε να διαβάζετε την υπόλοιπη τεκμηρίωση.
Κατάσταση έργου, χαρακτηριστικά και οπτικές επιδείξεις
Ένα άλλο σημαντικό τμήμα του README υποδεικνύει την τρέχουσα κατάσταση του έργου . Δεν είναι το ίδιο να εισάγετε ένα ώριμο εργαλείο με σταθερές εκδόσεις με το να εισάγετε κάτι που βρίσκεται στα αρχικά του στάδια, πειραματικό ή παγωμένο. Μπορείτε να το αντικατοπτρίσετε αυτό με ένα σήμα, μια γραμμή κειμένου ή και τα δύο.
Μια πολύ συνηθισμένη μορφή είναι η συμπερίληψη μιας σύντομης σημείωσης με emoji, όπως " Έργο υπό κατασκευή ", χρησιμοποιώντας τη σύνταξη emoji του GitHub στο Markdown ή εισάγοντας απευθείας το εικονίδιο. Τοποθετήστε το σε μια υποεπικεφαλίδα ή κεντράροντάς το χρησιμοποιώντας <h4 align="center"> Προσφέρει ορατότητα χωρίς να καταλαμβάνει πολύ χώρο.
Αμέσως μετά ακολουθεί συνήθως μια λίστα με τα κύρια χαρακτηριστικά του έργου . Ο στόχος εδώ δεν είναι να απαριθμήσουμε κάθε λεπτομέρεια, αλλά να ομαδοποιήσουμε τις βασικές δυνατότητες σε σαφή σημεία: τι μπορεί να κάνει ένας χρήστης με την εφαρμογή σας, ποια τελικά σημεία εκθέτει το API σας, ποιες λειτουργίες καλύπτει η βιβλιοθήκη σας και ούτω καθεξής.
Για να μεγιστοποιήσετε τον αντίκτυπο, είναι καλή ιδέα να συνοδεύσετε αυτές τις λειτουργίες με μια οπτική επίδειξη . Μπορείτε να εγγράψετε ένα GIF της διεπαφής εν δράσει, να τραβήξετε σχετικά στιγμιότυπα οθόνης ή ακόμα και να δημιουργήσετε έναν σύνδεσμο προς ένα σύντομο βίντεο. Η εισαγωγή εικόνων ή GIF ακολουθεί το ίδιο μοτίβο όπως πριν: είτε σύρετε το αρχείο στον επεξεργαστή GitHub είτε ανεβάστε το σε έναν φάκελο στο αποθετήριο και δημιουργήστε έναν σύνδεσμο προς αυτό χρησιμοποιώντας τη σχετική διαδρομή του.
Εάν το έργο σας δεν διαθέτει γραφική διεπαφή (για παράδειγμα, είναι ένα πακέτο backend ή μια βιβλιοθήκη), μπορείτε να δείξετε παραδείγματα χρήσης στον κώδικα και στην έξοδο κονσόλας , ώστε οι χρήστες να κατανοήσουν τι κάνει στην πραγματικότητα το εργαλείο σας όταν το εκτελούν.
Εγκατάσταση, υλοποίηση και πρακτική χρήση
Μόλις κάποιος καταλάβει τι κάνει το έργο σας και πειστεί ότι αξίζει τον κόπο, το επόμενο πράγμα που θα αναζητήσει είναι πώς να το εγκαταστήσει και να το εκτελέσει. Η ενότητα εγκατάστασης θα πρέπει να εξηγεί βήμα προς βήμα πώς να προετοιμάσετε το περιβάλλον , από την κλωνοποίηση του αποθετηρίου έως την εκκίνηση της εφαρμογής.
Είναι συνήθης πρακτική να συμπεριλαμβάνεται ένα μικρό μπλοκ με βασικές εντολές, όπως πώς να κλωνοποιήσετε το αποθετήριο, να πλοηγηθείτε στον φάκελο του έργου και να εγκαταστήσετε εξαρτήσεις χρησιμοποιώντας τον κατάλληλο διαχειριστή: npm, pip, Maven, Composer ή όποιον άλλον είναι κατάλληλο . Εάν απαιτούνται μεταβλητές περιβάλλοντος, εξωτερικές υπηρεσίες ή πρόσθετα βήματα, θα πρέπει επίσης να αναφέρονται με σαφήνεια σε αυτήν την ενότητα.
Στη συνέχεια, στην ενότητα χρήσης, περιγράφετε πώς εκτελείται το έργο και ποιες εντολές ή διαδρομές είναι σχετικέςΣε μια διαδικτυακή εφαρμογή, αυτό μπορεί να είναι τόσο απλό όσο ένα npm start και η τοπική διεύθυνση URL πρόσβασης· σε ένα API θα μπορούσατε να τεκμηριώσετε τις κύριες διαδρομές, τα παραδείγματα παραμέτρων και τις απαντήσεις· σε ένα εργαλείο κονσόλας, τις επιλογές που χρησιμοποιούνται περισσότερο.
Όσο πιο συγκεκριμένοι είστε με μικρά παραδείγματα, τόσο πιο εύκολο θα είναι για έναν χρήστη που χρησιμοποιεί για πρώτη φορά την εφαρμογή να τα θέσει σε λειτουργία χωρίς να απογοητευτεί. Η προσθήκη στιγμιότυπων οθόνης ή GIF που δείχνουν την εφαρμογή εν δράσει συμπληρώνει πολύ καλά αυτήν την ενότητα, ειδικά σε έργα τελικών χρηστών.
Εάν το έργο σας αναπτύσσεται σε περιβάλλον παραγωγής ή δοκιμών, είναι σημαντικό να συνδέσετε την ηλεκτρονική έκδοση ή την προσβάσιμη επίδειξη . Πολλοί άνθρωποι προτιμούν να το δοκιμάσουν απευθείας εκεί και μόνο αργότερα να κλωνοποιήσουν τον κώδικα για να τον εξερευνήσουν με την ησυχία τους.
Τεχνολογίες που χρησιμοποιούνται, δομή και δοκιμές
Μια πολύ χρήσιμη ενότητα, ειδικά αν χρησιμοποιείτε το GitHub ως χαρτοφυλάκιο, είναι η λίστα με τις τεχνολογίες, τις γλώσσες, τα πλαίσια και τα εργαλεία που εμπλέκονται στο έργο . Αυτή η ενότητα επιτρέπει σε οποιονδήποτε βλέπει το αποθετήριό σας να δει με μια ματιά με ποια στοίβα εργάζεστε.
Μπορείτε να απαριθμήσετε στοιχεία όπως η κύρια γλώσσα, το frontend ή το backend framework, η βάση δεδομένων, τα συστήματα ανάπτυξης, οι βιβλιοθήκες κλειδιών ή τα εργαλεία δοκιμών. Δεν χρειάζεται να είναι εγκυκλοπαίδεια, αλλά θα πρέπει να αντικατοπτρίζει με ακρίβεια τι έχετε πραγματικά εργαστεί κατά την ανάπτυξη αυτού του αποθετηρίου.
Σε πιο σύνθετα έργα, είναι επίσης χρήσιμο να συμπεριλάβετε ένα μικρό διάγραμμα της δομής του αρχείου ή της ενότητας , που να δείχνει τους κύριους καταλόγους και τον σκοπό τους. Ένα δέντρο φακέλων με τα πιο σχετικά αρχεία σάς βοηθά να προσανατολίζεστε γρήγορα χωρίς να χρειάζεται να ανοίγετε κάθε διαδρομή μία προς μία.
Αν έχετε αφιερώσει χρόνο γράφοντας δοκιμές, είναι καλή ιδέα να προσθέσετε μια ειδική ενότητα που να εξηγεί τους διαφορετικούς τύπους δοκιμών και τον τρόπο εκτέλεσής τους . Μπορείτε να περιγράψετε λεπτομερώς ποια εντολή εκκινεί τις δοκιμές μονάδας ή ολοκλήρωσης, αν υπάρχει αυτοματοποιημένη κάλυψη δοκιμών ή αν χρησιμοποιείτε εξωτερικές υπηρεσίες για συνεχή ολοκλήρωση.
Αυτές οι πρόσθετες ενότητες όχι μόνο βελτιώνουν την εμπειρία για όποιον θέλει να συνεισφέρει ή να επαναχρησιμοποιήσει τον κώδικά σας, αλλά ενισχύουν επίσης την εικόνα ενός σοβαρού και συντηρήσιμου έργου, σε αντίθεση με τα πιο αυτοσχέδια αποθετήρια όπου τίποτα από αυτά δεν τεκμηριώνεται.
Συντελεστές, συγγραφείς και η κοινότητα που περιβάλλει το έργο
Εάν το αποθετήριό σας δέχεται συνεισφορές ή έχει ήδη λάβει εξωτερικές συνεισφορές, η ενότητα «συνεισφέροντες» είναι ένα εξαιρετικό μέρος για να ευχαριστήσετε και να δώσετε προβολή σε όσους έχουν συμμετάσχει . Αυτό χτίζει μια κοινότητα και καταδεικνύει ότι το έργο δεν είναι μια μεμονωμένη προσπάθεια.
Πολλά έργα εμφανίζουν ένα πλέγμα με τα avatar των συνεισφερόντων στο GitHub, συνδεδεμένο με τα προφίλ τους ή χρησιμοποιούν υπηρεσίες όπως το contrib.rocks για να δημιουργήσουν αυτόματα μια εικόνα με όλους όσους έχουν συνεισφέρει . Μια άλλη επιλογή είναι ένας πίνακας Markdown με μια μικρή φωτογραφία, ένα όνομα και έναν σύνδεσμο προφίλ.
Είναι σημαντικό να γίνεται διάκριση μεταξύ των περιστασιακών συνεισφερόντων και των κύριων συγγραφέων του έργου. Στην ενότητα συγγραφέων, μπορείτε να συστηθείτε και να παρουσιάσετε την υπόλοιπη βασική ομάδα με μια μικρή φωτογραφία ή avatar, το όνομά σας και έναν σύνδεσμο προς το προφίλ σας στο GitHub ή σε άλλα επαγγελματικά δίκτυα.
Σε έργα με ενεργή κοινότητα, είναι επίσης λογικό να προσθέτετε συνδέσμους προς εξωτερικά κανάλια υποστήριξης ή συζήτησης , όπως έναν διακομιστή Discord, έναν λογαριασμό Twitter, έναν επίσημο ιστότοπο ή εξωτερική τεκμηρίωση. Αυτό διευκολύνει τους χρήστες να γνωρίζουν πού να υποβάλλουν ερωτήσεις, να προτείνουν βελτιώσεις ή να παραμένουν ενημερωμένοι για τα τελευταία νέα.
Αν θέλετε να ενθαρρύνετε τις συνεισφορές, συνιστάται να δημιουργήσετε έναν σύνδεσμο προς ένα συγκεκριμένο έγγραφο με οδηγίες για συνεργασία: οδηγό στυλ κώδικα, διαδικασία ανοίγματος ζητημάτων, πρότυπο για αιτήματα έλξης ή ακόμα και έναν κώδικα δεοντολογίας, όπως η Σύμβαση Συνεισφοράς.
Άδεια χρήσης και νομικές πτυχές του αποθετηρίου
Έχουμε φτάσει σε μια ενότητα που πολλοί αρχάριοι παραβλέπουν αλλά είναι κρίσιμη: την άδεια χρήσης. Ένα δημόσιο έργο στο GitHub δεν είναι πραγματικά ελεύθερο ή λογισμικό ανοιχτού κώδικα με τη νομική έννοια, εάν δεν καθορίσετε τους όρους υπό τους οποίους μπορεί να χρησιμοποιηθεί, να τροποποιηθεί και να αναδιανεμηθεί.
Η καλύτερη πρακτική είναι να συμπεριλάβετε ένα αρχείο LICENSE στον ριζικό κατάλογο του αποθετηρίου με το πλήρες κείμενο της επιλεγμένης άδειας χρήσης (MIT, Apache 2.0, GPL, Creative Commons, κ.λπ.) και, επιπλέον, Αναφέρετε σύντομα στο README ποια άδεια χρήσης ισχύει.Για παράδειγμα, μια γραμμή που υποδεικνύει ότι ο κώδικας έχει άδεια χρήσης από το MIT και ότι συγκεκριμένη τεκμηρίωση έχει διαφορετική άδεια χρήσης.
Αν δεν είστε σίγουροι ποια άδεια χρήσης να επιλέξετε, πηγές όπως το ChooseALicense.com μπορούν να σας βοηθήσουν να συγκρίνετε επιλογές και να κατανοήσετε τις επιπτώσεις της καθεμίας. Η επιλογή της σωστής άδειας χρήσης είναι σημαντική είτε θέλετε να διευκολύνετε την επαγγελματική χρήση του κώδικά σας είτε να διασφαλίσετε ότι οι βελτιώσεις κοινοποιούνται υπό τους ίδιους όρους.
Στο README, αρκεί μια τελευταία ενότητα που καθορίζει τον τύπο άδειας χρήσης και τους συνδέσμους προς το αντίστοιχο αρχείο. Αυτό το μικρό βήμα παρέχει σαφήνεια σε όποιον θέλει να επαναχρησιμοποιήσει το έργο σας ή να το ενσωματώσει σε μεγαλύτερα έργα χωρίς φόβο νομικών ζητημάτων.
Ορισμένα έργα προχωρούν ένα βήμα παραπέρα και κάνουν διάκριση μεταξύ μιας άδειας χρήσης κώδικα και μιας άδειας χρήσης για τεκμηρίωση ή γραφικούς πόρους, κάτι που είναι πολύ χρήσιμο αν, για παράδειγμα, θέλετε να διατηρήσετε κάποια προστασία πάνω από την επωνυμία ή το υλικό των εγγράφων, αλλά να απελευθερώσετε πλήρως τη βάση κώδικα.
Προφίλ GitHub README και άλλα προηγμένα κόλπα
Εκτός από το README για κάθε έργο, το GitHub σάς επιτρέπει να δημιουργήσετε ένα ειδικό README που σχετίζεται με το δικό σας προφίλ . Αυτός είναι ένας πολύ χρήσιμος τρόπος για να συστηθείτε ως προγραμματιστής, να επιδείξετε τις δεξιότητές σας, να επισημάνετε έργα και να δώσετε στοιχεία επικοινωνίας.
Για να το ενεργοποιήσετε, πρέπει να δημιουργήσετε ένα δημόσιο αποθετήριο με το ίδιο όνομα με το όνομα χρήστη σας στο GitHub και να συμπεριλάβετε ένα αρχείο README.md στον ριζικό κατάλογο και γεμίστε τον με περιεχόμενο. Το GitHub θα εμφανίσει αυτόματα αυτό το αρχείο README στην κορυφή του δημόσιου προφίλ σας, όπως μια επαγγελματική κάρτα.
Εάν διαγράψετε αυτό το αρχείο, αδειάσετε το περιεχόμενό του, αλλάξετε το όνομα του αποθετηρίου ή το κάνετε ιδιωτικό, το αρχείο README δεν θα εμφανίζεται πλέον στο προφίλ σας . Επομένως, είναι καλύτερο να το αντιμετωπίζετε όπως οποιοδήποτε άλλο αποθετήριο και να το διατηρείτε ενημερωμένο, ειδικά εάν το χρησιμοποιείτε για να παρουσιάσετε τα πιο σημαντικά έργα ή τις αγαπημένες σας τεχνολογίες.
Όσον αφορά τον σχεδιασμό, το README του προφίλ σας σάς επιτρέπει να χρησιμοποιήσετε πολλούς από τους πόρους που έχουμε συζητήσει: λογότυπα, κεντραρισμένες εικόνες, τεχνολογικά σήματα, μετρητές αστεριών, συνδέσμους προς κοινωνικά δίκτυα και μικρές επισημασμένες ενότητες . Είναι το ιδανικό μέρος για να συνοψίσετε ποιοι είστε επαγγελματικά χωρίς να αναγκάσετε κανέναν να ψάξει σε δεκάδες αποθετήρια.
Αν θέλετε να προχωρήσετε ένα βήμα παραπέρα, μπορείτε επίσης να χρησιμοποιήσετε μικρά οπτικά κόλπα στα README του έργου σας: κεντράρετε τα λογότυπα με μπλοκ HTML, χρησιμοποιήστε ετικέτες <picture> y <source> για να προσαρμόσετε εικόνες σε σκούρα ή ανοιχτόχρωμα θέματα, να εμφανίσετε γραφήματα που δείχνουν την εξέλιξη των αστεριών στο αποθετήριο ή να ενσωματώσετε δυναμικά δημιουργημένες λίστες συνεργατών.
Τελικά, ο συνδυασμός ενός καλού README για κάθε έργο και ενός καλογραμμένου προφίλ README μετατρέπει τον λογαριασμό σας στο GitHub σε ένα συμπαγές χαρτοφυλάκιο που είναι εύκολο για όποιον θέλει να μάθει για την εργασία σας: από recruiters έως άλλους προγραμματιστές που αναζητούν έργα για συνεργασία.
Όταν συνηθίσετε να σκέφτεστε το README ως θεμελιώδες μέρος της ανάπτυξης και όχι ως μια προσθήκη της τελευταίας στιγμής, τα αποθετήριά σας αρχίζουν να κερδίζουν ελκυστικότητα, σαφήνεια και συνοχή. Αυτό μεταφράζεται άμεσα σε μεγαλύτερο ενδιαφέρον, περισσότερα σχόλια και περισσότερες ευκαιρίες στο οικοσύστημα του GitHub.
