Τι είναι τα αρχεία README και πώς να τα χρησιμοποιήσετε σωστά

Αν εργάζεστε με ψηφιακά έργα, αργά ή γρήγορα θα συναντήσετε ένα αρχείο με το όνομα READMEΑν και μπορεί να φαίνεται σαν ένα απλό έγγραφο κειμένου, είναι πολύ πιο σημαντικό από ό,τι φαίνεται: είναι το συνοδευτική επιστολή για το έργο σας, το πρώτο σημείο εισόδου για όποιον θέλει να μάθει τι έχετε κάνει, πώς να το χρησιμοποιήσετε και αν αξίζει τον χρόνο του.

Στον κόσμο της ανάπτυξης λογισμικού, της επιστήμης δεδομένων ή ακόμα και σε ακαδημαϊκό έργο και συνεργατικά έργα, ένα README καλογραμμένο Σας εξοικονομεί χρόνο, αποτρέπει τα λάθη και διευκολύνει τους άλλους (ή ακόμα και εσάς τους ίδιους σε λίγους μήνες) να κατανοήσουν γρήγορα τον σκοπό του έργου. Ας ρίξουμε μια πιο προσεκτική ματιά στο τι είναι τα αρχεία README, σε τι χρησιμεύουν, τι πρέπει να περιλαμβάνουν και πώς να τα αξιοποιήσετε στο έπακρο.

Τι ακριβώς είναι ένα αρχείο README;

Ένα αρχείο README είναι ένα έγγραφο κειμένου που συνοδεύει ένα ψηφιακό έργο Ο κύριος στόχος του είναι να εξηγήσει με σαφήνεια τι περιέχει το έργο, σε τι χρησιμεύει και πώς να το χρησιμοποιήσει. Κυριολεκτικά μεταφρασμένο, θα ήταν κάτι σαν «διάβασέ με», και αυτή ακριβώς είναι η λειτουργία του: να είναι το πρώτο πράγμα που διαβάζει κάποιος όταν ανοίγει ένα αποθετήριο, έναν φάκελο δεδομένων ή ένα πακέτο λογισμικού.

Αυτός ο τύπος αρχείου μπορεί να αποθηκευτεί σε διαφορετικά μορφές κειμένου: από το κλασικό readme.txt (απλό κείμενο) έως readme.doc, readme.1st ή λιγότερο συνηθισμένες επεκτάσεις όπως Me.Η συγκεκριμένη μορφή συνήθως προσαρμόζεται σε λειτουργικό σύστημα και το πρόγραμμα με το οποίο θα εμφανίζεταιέτσι ώστε οποιοσδήποτε χρήστης να μπορεί να ανοίξει και να διαβάσει το αρχείο χωρίς καμία επιπλοκή.

Σήμερα, ειδικά σε έργα λογισμικού και αποθετήρια κώδικα, η πιο κοινή μορφή είναι README.mdΗ επέκταση .md υποδεικνύει ότι το αρχείο είναι γραμμένο σε Χαμήλωση τιμήςΗ HTML είναι μια πολύ απλή γλώσσα σήμανσης που σας επιτρέπει να μετατρέψετε κείμενο σε HTML χρησιμοποιώντας μόνο λίγα σύμβολα για μορφοποίηση. Αυτό διευκολύνει τη μορφοποίηση του περιεχομένου. εύκολο στην ανάγνωση τόσο σε ακατέργαστη όσο και σε αποδοσμένη μορφή σε διαδικτυακή μορφήεκτός από την δυνατότητα προσθήκης τίτλων, λιστών, συνδέσμων, πινάκων, εικόνων και άλλων χωρίς επιπλοκές.

Ένα καλά δομημένο README προσφέρει στον χρήστη ή τον συνεισφέροντα ένα πλήρης και κατανοητή περίληψη του έργουΔεν προορίζεται να αποτελέσει ένα εξαντλητικό έγγραφο, αλλά έναν πρακτικό οδηγό: τι κάνει το έργο, γιατί είναι χρήσιμο, πώς να αρχίσετε να το χρησιμοποιείτε και πού μπορείτε να βρείτε περισσότερες πληροφορίες, εάν χρειαστεί.

Στον τομέα των δεδομένων, για παράδειγμα σε αποθετήρια συνόλων δεδομένων, είναι πολύ συνηθισμένο το README (μερικές φορές σε μορφή) να είναι readme.txt) συλλέγω Γενικές πληροφορίες, συγγραφή, λέξεις-κλειδιά, γεωγραφική και χρονική κάλυψη, άδεια χρήσης και μεθοδολογία που χρησιμοποιούνται για τη δημιουργία ή τη συλλογή δεδομένων, καθώς και Προτεινόμενο λογισμικό για εργασία μαζί τους.

Σύντομο ιστορικό και τυπική χρήση των αρχείων README

Αν και σήμερα τα συνδέουμε κυρίως με πλατφόρμες όπως το GitHub, η πρακτική της συμπερίληψης ενός αρχείου README σε πακέτα λογισμικού προέρχεται από δεκαετίες πρινΥπάρχουν τεκμηριωμένα παραδείγματα που χρονολογούνται από το μέσα της δεκαετίας του 70, όταν τα προγράμματα διανέμονταν ήδη με ένα μικρό έγγραφο που εξηγούσε το περιεχόμενο και τη χρήση τους.

Με την πάροδο του χρόνου, η πρακτική καθιερώθηκε τόσο πολύ που Πρότυπα Κωδικοποίησης GNU (πρότυπα κωδικοποίησης GNU) το αρχείο README θεωρείται μια απαίτησηΑυτά τα πρότυπα επηρέασαν σε μεγάλο βαθμό το οικοσύστημα του ελεύθερου λογισμικού και συνέβαλαν στο να καταστεί το αρχείο README σχεδόν υποχρεωτικό σε οποιοδήποτε σοβαρό πακέτο λογισμικού.

Όταν ο ιστός έγινε το τυποποιημένη πλατφόρμα για τη διανομή λογισμικούΠολλά έργα άρχισαν να μεταφέρουν ορισμένες από τις πληροφορίες που υπήρχαν προηγουμένως στο README (εγχειρίδια, άδεια χρήσης, νέα κ.λπ.) σε ιστότοπους, wiki ή στο πακέτο πηγαίου κώδικα tarballΑκόμα κι έτσι, το αρχείο README δεν εξαφανίστηκε ποτέ: σε πολλές περιπτώσεις παρέμεινε ως εξής: τοπική σύνοψηαν και μερικές φορές παρέμενε κάπως ελλιπής σε σύγκριση με την ηλεκτρονική τεκμηρίωση.

Η δημοτικότητα πλατφορμών όπως η GitHub Και οι προσπάθειες πιο καθιερωμένων κοινοτήτων ελεύθερου λογισμικού έχουν επαναφέρει τα αρχεία README στο προσκήνιο. Στο GitHub, για παράδειγμα, εάν ένα αποθετήριο περιέχει ένα αρχείο README στον ριζικό κατάλογο, το σύστημα θα το προσθέσει αυτόματα. Μετατρέπει αυτόματα σε HTML και το εμφανίζει στην αρχική σελίδα του έργου, επομένως είναι το πρώτο πράγμα που βλέπετε όταν μπαίνετε.

Επιπλέον, η έννοια του «αρχείου readme» χρησιμοποιείται μερικές φορές σε ένα γενικός Για να αναφερθείτε σε οποιοδήποτε σύντομο έγγραφο που εξηγεί τα περιεχόμενα ενός φακέλου ή έργου, ακόμα κι αν το αρχείο δεν ονομάζεται ακριβώς README. Πολλά έργα ελεύθερου λογισμικού διανέμουν ένα τυπικό σύνολο αρχείων μαζί με το README, το καθένα με μια σαφώς καθορισμένη λειτουργία.

Τυπικά αρχεία που συνοδεύουν ένα README

Σε έργα που ακολουθούν πρότυπα όπως Πρότυπα Gnits ή αυτά που δημιουργούνται με εργαλεία όπως Αυτόματα εργαλεία GNUΕκτός από το κύριο αρχείο README, είναι σύνηθες να βρείτε και άλλα αρχεία κειμένου που συμπληρώνουν τις πληροφορίες του έργου. Μερικά από τα πιο συνηθισμένα είναι:

• README: γενικές πληροφορίες σχετικά με το έργο, τον σκοπό και το συνολικό όραμα.
• ΣΥΓΓΡΑΦΕΙΣ: λίστα κύριων συγγραφέων ή συνεργατών.
• ΕΥΧΑΡΙΣΤΩ: ευχαριστίες σε άτομα ή ιδρύματα που βοήθησαν.
• CHANGELOG: λεπτομερές αρχείο καταγραφής αλλαγών, σχεδιασμένο κυρίως για προγραμματιστές.
• ΝΈΑ: ένα πιο συνοπτικό και κατανοητό αρχείο καταγραφής αλλαγών για τους τελικούς χρήστες.
• ΕΓΚΑΤΑΣΤΑΣΗ: συγκεκριμένες οδηγίες εγκατάστασης και τεχνικές απαιτήσεις.
• ΑΝΤΙΓΡΑΦΗ / ΑΔΕΙΑ ΧΡΗΣΗΣ: κείμενο της άδειας χρήσης και διανομής λογισμικού.
• BUGSΓνωστά σφάλματα και τρόποι σωστής αναφοράς τους.
• Συχνές ΕρωτήσειςΣυχνές ερωτήσεις και οι απαντήσεις τους.
• TODO: λίστα εκκρεμών εργασιών και προγραμματισμένες μελλοντικές βελτιώσεις.

Όλα αυτά τα έγγραφα, μαζί με το αρχείο README, αποτελούν ο σκελετός της βασικής τεκμηρίωσης πολλών πακέτων. Σε ορισμένες περιπτώσεις, ορισμένες από αυτές τις πληροφορίες αντιγράφονται τόσο στο αποθετήριο όσο και στον ιστότοπο του έργου για να διευκολυνθεί η πρόσβαση από διαφορετικά κανάλια.

Ο ρόλος του README στο GitHub και σε παρόμοιες πλατφόρμες

Στο GitHub, το αρχείο README παίζει ιδιαίτερα σημαντικό ρόλο. Αρχικά, συνήθως είναι το πρώτο πράγμα που βλέπει κάποιος που επισκέπτεται το αποθετήριό σαςΑν το αρχείο είναι σωστά γραμμένο, σε λίγα δευτερόλεπτα θα είναι σαφές τι κάνει το έργο, γιατί μπορεί να είναι ενδιαφέρον, πώς να το θέσετε σε λειτουργία και ποιος βρίσκεται πίσω από αυτό.

Το GitHub αναγνωρίζει αυτόματα το αρχείο README όταν τοποθετείται σε συγκεκριμένες θέσεις αποθετηρίου. Εάν το τοποθετήσετε στον φάκελο .github, Στο ριζικό κατάλογο ή στο φάκελο docsη πλατφόρμα το εντοπίζει και εμφανίζει σε περίοπτη θέση στους επισκέπτες. Όταν υπάρχουν πολλά αρχεία README, το GitHub ακολουθεί ένα σειρά προτεραιότητας: πρώτη αναζήτηση σε .github, έπειτα στη ρίζα και τέλος στο docs.

Επιπλέον, εάν δημιουργήσετε ένα δημόσιο αποθετήριο του οποίου το όνομα ταιριάζει ακριβώς με το όνομα χρήστη Και αν προσθέσετε ένα αρχείο README στον ριζικό κατάλογο, αυτό το αρχείο γίνεται αυτόματα το αρχείο README σας. Προφίλ READMEΕμφανίζεται στη σελίδα χρήστη σας, επιτρέποντάς σας να δημιουργήσετε μια προσαρμοσμένη ενότητα παρουσίασης χρησιμοποιώντας το GitHub Flavored Markdown.

Όταν ένα αρχείο README (ή οποιοδήποτε αρχείο .md) προβάλλεται στο GitHub, η πλατφόρμα δημιουργεί αυτόματα ένα Πίνακας περιεχομένων με βάση τους τίτλους των εγγράφων. Μπορείτε να δείτε αυτό το ευρετήριο κάνοντας κλικ στο εικονίδιο "Περίγραμμα", το οποίο διευκολύνει πολύ την πλοήγηση σε μεγάλα αρχεία README με πολλαπλές ενότητες.

Το GitHub επιτρέπει επίσης σύνδεσμος απευθείας σε συγκεκριμένες ενότητεςΚάθε επικεφαλίδα δημιουργεί αυτόματα μια άγκυρα. Απλώς τοποθετώντας τον δείκτη του ποντικιού πάνω από τον τίτλο θα εμφανιστεί το εικονίδιο συνδέσμου. Αυτό σας επιτρέπει να κοινοποιείτε διευθύνσεις URL που οδηγούν απευθείας στη συγκεκριμένη ενότητα του README που θέλετε να επισημάνετε (για παράδειγμα, την ενότητα εγκατάστασης ή συνεισφορών).

Υπάρχει μια σημαντική πρακτική λεπτομέρεια: για λόγους απόδοσης, εάν το README σας υπερβαίνει το 500 KiB μεγέθους, GitHub θα περικόψει το περιεχόμενο Από εκείνο το σημείο και μετά στην προβολή απόδοσης. Επομένως, συνιστάται να κρατάτε το README για βασικές πληροφορίες και να μετακινείτε μακροσκελή εκπαιδευτικά κείμενα ή εγχειρίδια σε wiki ή σε ξεχωριστή τεκμηρίωση.

Μορφή και σύνδεσμοι μέσα σε ένα README

Για να είναι εύκολο στη συντήρηση και να λειτουργεί καλά το README τόσο στο GitHub όσο και σε τοπικούς κλώνους, συνιστάται η χρήση του σχετικοί σύνδεσμοι και διαδρομές εικόνας σε σχέση με το αρχείο όπου βρίσκονται. Έτσι, για παράδειγμα, εάν έχετε ένα αρχείο README στον ριζικό κατάλογο και ένα έγγραφο docs/CONTRIBUTING.mdΟ σύνδεσμος μέσα στο README θα μοιάζει κάπως έτσι: (docs/CONTRIBUTING.md).

Αυτός ο τύπος σχετικής σύνδεσης σημαίνει ότι κατά την εναλλαγή κλάδων ή την κλωνοποίηση του αποθετηρίου, οι διαδρομές συνεχίζουν να λειτουργούν σωστά χωρίς να χρειάζεται να τις τροποποιήσετε. Το GitHub μετασχηματίζει εσωτερικά αυτές τις διαδρομές ώστε να δείχνουν στη σωστή έκδοση αρχείου με βάση τον εμφανιζόμενο κλάδο. Διαδρομές που ξεκινούν με /τα οποία ερμηνεύονται σε σχέση με τη ρίζα του αποθετηρίου, καθώς και κοινούς τελεστές όπως ./ o ../.

Είναι σημαντικό ότι το κείμενο συνδέσμου Διατηρήστε τον σύνδεσμο σε μία μόνο γραμμή, καθώς ο διαχωρισμός του σε πολλές γραμμές μπορεί να προκαλέσει δυσλειτουργία. Επιπλέον, αποφύγετε τους απόλυτους συνδέσμους προς εσωτερικά αρχεία αποθετηρίου, καθώς αυτά μπορεί να σπάσουν εάν αλλάξει η βασική διεύθυνση URL ή δημιουργηθεί μια διακλάδωση.

Όσον αφορά το πεδίο εφαρμογής του εγγράφου, αξίζει να θυμόμαστε ότι το README θα πρέπει να περιέχει μόνο τις απαραίτητες πληροφορίες για να ξεκινήσετε να χρησιμοποιείτε και να συνεισφέρετε στο έργο. Για εκτενή τεκμηρίωση (εγχειρίδια χρήστη, πλήρεις οδηγοί API, κ.λπ.), είναι πιο εύκολο να χρησιμοποιήσετε ένα wiki ή ένα ξεχωριστό σύστημα τεκμηρίωσης, που θα το συνδέει με το ίδιο το README.

Ποιος είναι ο πραγματικός σκοπός ενός αρχείου README;

Πέρα από τη θεωρία, το αρχείο README λειτουργεί στην πράξη ως αρχικός οδηγός και σημείο αναφοράςΔεν έχει σκοπό να αντικαταστήσει την εκτενή επίσημη τεκμηρίωση, αλλά μάλλον να προσφέρει μια οργανωμένη και πρακτική εξήγηση των πιο σημαντικών πτυχών του έργου.

Μεταξύ των πιο συνηθισμένων χρήσεών του είναι: εξηγήστε τον στόχο του έργου, περιγράψτε ποια δεδομένα ή αρχεία περιλαμβάνει, υποδείξτε πώς να ξεκινήσετε να το χρησιμοποιείτε και προσδιορίστε τις βασικές τεχνικές απαιτήσεις και αποφύγετε σφάλματα που προκαλούνται από ακατάλληλη χρήσηΌταν πολλοί χρήστες εργάζονται στον ίδιο κώδικα ή δεδομένα, ένα σαφές README γλιτώνει από ατελείωτες επαναλαμβανόμενες ερωτήσεις.

Σε κοινά έργα, ειδικά σε μεγάλες ομάδες ή κοινότητες ανοιχτού κώδικα, το README είναι σχεδόν ένα στοιχείο υποδομής επικοινωνιώνΧρησιμεύει στην ευθυγράμμιση των προσδοκιών, στην υπόδειξη του επιπέδου ωριμότητας του έργου, στον καθορισμό του τρόπου με τον οποίο κάποιος συνεισφέρει και στην αποσαφήνιση της υποστήριξης που προσφέρεται (εάν υπάρχει).

Ακόμα και σε προσωπικά έργα, ακόμα κι αν μόνο εσείς θα εργάζεστε σε αυτά, ένα καλογραμμένο README λειτουργεί ως μακροπρόθεσμη μνήμηΜε την πάροδο του χρόνου είναι εύκολο να ξεχάσετε αποφάσεις, εξαρτήσεις ή βήματα εγκατάστασης. Η τεκμηρίωσή τους σας γλιτώνει από το να χρειαστεί να «ανακαλύψετε ξανά» το δικό σας έργο μήνες αργότερα.

Επομένως, το README δεν είναι απλώς μια τυπική διαδικασία: είναι ένα πρακτικό εργαλείο που βελτιώνει οργάνωση, επικοινωνία και συντηρησιμότητα οποιουδήποτε είδους ψηφιακού έργου.

Πότε είναι κατάλληλη η δημιουργία ενός αρχείου README;

Η σύντομη απάντηση είναι ότι είναι καλή ιδέα να δημιουργήσετε ένα αρχείο README. κάθε φορά που υπάρχει ένα έργο που πρόκειται να χρησιμοποιηθεί, να αναθεωρηθεί ή να συντηρηθεί από κάποιον άλλον εκτός από τον αρχικό δημιουργό... και αυτό περιλαμβάνει και τον μελλοντικό σας εαυτό. Δεν χρειάζεται να είναι ένα τεράστιο αποθετήριο ανοιχτού κώδικα: απλώς χρειάζεται να έχει κάποια πολυπλοκότητα ή το περιεχόμενο να εγείρει ερωτήματα.

Μερικά παραδείγματα όπου ένα αρχείο README είναι ιδιαίτερα χρήσιμο είναι τα εξής: έργα ιστού ή προγραμματισμούόπου είναι σκόπιμο να εξηγηθούν οι απαιτήσεις, οι διαδικασίες ανάπτυξης, οι εντολές εκκίνησης και το περιβάλλον εκτέλεσης. Είναι επίσης πολύ ενδιαφέρον το φακέλους με σημαντικά δεδομέναγια να διευκρινιστεί τι αντιπροσωπεύουν αυτά τα δεδομένα, η προέλευσή τους και οι πιθανοί περιορισμοί τους.

Άλλα τυπικά πλαίσια είναι τα ιστοσελίδες που φιλοξενούνται σε hostingτα οποία συχνά περιλαμβάνουν ένα README με οδηγίες ανάπτυξης ή το ακαδημαϊκά και τεχνικά έργα, στο οποίο το README μπορεί να περιγράψει σενάρια, πειράματα, εκδόσεις εργαλείων που χρησιμοποιούνται ή πώς να αναπαράγει αποτελέσματα.

En συνεργατικά έργαΕίτε εσωτερικό είτε δημόσιο, το README είναι σχεδόν υποχρεωτικό. Βοηθά τους νέους χρήστες να συμμετέχουν στο έργο πιο ομαλά και λειτουργεί ως κοινόχρηστο σημείο αναφοράς για τη διατήρηση σταθερών προτύπων χρήσης και συνεισφοράς μεταξύ όλων των ενδιαφερόμενων μερών.

Ποιες πληροφορίες πρέπει να περιέχει ένα καλό README;

Ένα αποτελεσματικό README δεν χρειάζεται να είναι μεγάλο, αλλά πρέπει να είναι καλά οργανωμένο και πολύ σαφέςΥπάρχουν κάποιες βασικές πληροφορίες που σχεδόν πάντα θα πρέπει να περιλαμβάνονται, καθώς και άλλο προαιρετικό περιεχόμενο που προσθέτει μεγάλη αξία ανάλογα με τον τύπο του έργου.

Κατ' ελάχιστον, τα περισσότερα καλά τεκμηριωμένα αποθετήρια και πακέτα περιλαμβάνουν το όνομα έργου, Ένα σύντομη περιγραφή του στόχου, μια σύνοψη του περιεχομένου του αποθετηρίου, το Οδηγίες για τη χρήση ή την εγκατάστασή του και τις βασικές απαιτήσεις (εξαρτήσεις, ελάχιστη έκδοση γλώσσας, λειτουργικό σύστημα κ.λπ.).

Συνιστάται επίσης ιδιαίτερα να προσθέσετε μερικά μέθοδος επικοινωνίας ή υποστήριξηςΑκόμα κι αν πρόκειται απλώς για ένα email ή έναν σύνδεσμο προς την ενότητα "Προβλήματα" του αποθετηρίου, αυτό καθοδηγεί όποιον αντιμετωπίζει προβλήματα σχετικά με το πού και πώς να τα αναφέρει, αντί να τον αφήνει χαμένο και αβέβαιο για το ποιον να επικοινωνήσει.

Εκτός από τα βασικά, είναι συχνά χρήσιμο να συμπεριλάβετε πληροφορίες σχετικά με το ημερομηνία δημιουργίας ή έκδοση τρέχουσα, ο κατάλογος των συγγραφέων ή των υπευθύνων, το άδεια χρήσης και τυχόν σχετικές ειδοποιήσεις σχετικά με τη χρήση των δεδομένων ή του κώδικα (για παράδειγμα, εάν πρόκειται για πειραματική έκδοση ή δεν είναι κατάλληλη για παραγωγή).

Η σειρά επηρεάζει επίσης την αναγνωσιμότητα: οι πιο κρίσιμες πληροφορίες (τι είναι το έργο, σε τι χρησιμεύει, πώς χρησιμοποιείται) θα πρέπει να εμφανίζονται πρώτες. στην αρχή του εγγράφουαφήνοντας δευτερεύουσες λεπτομέρειες, εκτεταμένες αναφορές ή ιστορικές σημειώσεις για αργότερα. Με αυτόν τον τρόπο, κάποιος που απλώς περιηγείται μπορεί να σχηματίσει μια σαφή ιδέα με μια γρήγορη ματιά.

Τυπικό περιεχόμενο ενός README σε λογισμικό

Σε έργα λογισμικού, τα αρχεία README συχνά προχωρούν ένα βήμα παραπέρα και περιλαμβάνουν αρκετά επιπλέον θεματικά μπλοκ. Σε πολλές περιπτώσεις, το αρχείο συνοψίζει συνοπτικά οδηγίες εγκατάστασης, οδηγίες εγκατάστασης, βασικές οδηγίες χρήσης, ένα μανιφέστο αρχείου (εξηγήστε σε τι χρησιμεύει κάθε σημαντικός φάκελος) και μια σύνοψη της άδειας χρήσης.

Είναι επίσης σύνηθες να συμπεριλαμβάνεται μια ενότητα με πληροφορίες σχετικά με τον προγραμματιστή ή την ομάδα, πιθανούς τρόπους συνεισφοράς στο έργο, μια λίστα με γνωστά σφάλματα και έναν σύντομο οδηγό αντιμετώπισης προβλημάτων για συνηθισμένα προβλήματα. Όλα αυτά βοηθούν όποιον επισκέπτεται το αποθετήριο να έχει ένα παγκόσμιο και πρακτικό όραμα χωρίς να χρειάζεται να ψάξεις αλλού.

Σε ορισμένες περιπτώσεις, το README ενδέχεται να περιέχει ένα μικρό Αλλαγή αρχείου καταγραφής ή να παραπέμπουν σε ένα εξωτερικό αρχείο CHANGELOG. Είναι επίσης αρκετά συνηθισμένο να συμπεριλαμβάνεται μια ενότητα "Νέα" ή "Τι νέο υπάρχει" που επισημαίνει τις σχετικές αλλαγές μεταξύ εκδόσεων, ειδικά όταν το κοινό-στόχος είναι οι τελικοί χρήστες και όχι οι προγραμματιστές.

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

Το README ως εργαλείο επικοινωνίας στο GitHub

Όταν ανεβάζετε ένα έργο στο GitHub, το README δεν γίνεται μόνο τεκμηρίωση, αλλά και στοιχείο επικοινωνίας και παρουσίασηςΣτην πραγματικότητα, η ίδια η πλατφόρμα συνιστά την προσθήκη ενός README σε οποιοδήποτε δημόσιο αποθετήριο για να βοηθήσει τους επισκέπτες να κατανοήσουν γρήγορα περί τίνος πρόκειται το έργο.

Μπορείτε να χρησιμοποιήσετε το README για να εξηγήσετε τι κάνει το έργοΓιατί μπορεί να είναι χρήσιμο, πώς να ξεκινήσετε (για παράδειγμα, με μια ενότητα "Ξεκινώντας"), πού να λάβετε βοήθεια (προβλήματα, φόρουμ, συνομιλία κ.λπ.) και ποιος συντηρεί ενεργά τον κώδικα. Όλα αυτά επηρεάζουν την αντιληπτή ποιότητα και την εμπιστοσύνη που δημιουργεί το αποθετήριο.

Σε πολλές περιπτώσεις, οι προγραμματιστές χρησιμοποιούν τα αποθετήρια GitHub ως επαγγελματικό χαρτοφυλάκιοΣε αυτό το πλαίσιο, τα καλοσχεδιασμένα README κάνουν τεράστια διαφορά: επιτρέπουν στους υπεύθυνους προσλήψεων ή σε άλλα ενδιαφερόμενα μέρη να δουν, με μια ματιά, το εύρος του έργου, τις τεχνολογίες που χρησιμοποιούνται και τις μεθόδους εργασίας του συγγραφέα.

Εάν η πρόθεσή σας δεν είναι να προσελκύσετε συνεισφορές ή να προωθήσετε το αποθετήριο (για παράδειγμα, εάν πρόκειται για ιδιωτικό ή πολύ εσωτερικό έργο), ένα πολύ λεπτομερές README δεν είναι υποχρεωτικό. Ακόμα κι έτσι, είναι συνήθως πρακτικό να διατηρείτε τουλάχιστον ένα. ελάχιστη βασική τεκμηρίωση για προσωπική και ομαδική χρήση.

Το GitHub προσφέρει επίσης ορισμένα συγκεκριμένα βοηθητικά προγράμματα που σχετίζονται με το README: δημιουργεί αυτόματα ένα ευρετήριο, υποστηρίζει badges και εικονίδια και σας επιτρέπει να εισάγετε εικόνες, GIF ή βίντεο για να παρουσιάσετε το έργο. Όταν χρησιμοποιούνται αποτελεσματικά, όλα αυτά τα στοιχεία μπορούν να κάνουν το README πιο αποτελεσματικό. πιο ελκυστικό και πιο εύκολο στην πλοήγηση.

Πώς να δομήσετε και να βελτιώσετε το README σας

Κατά την ανάλυση δημοφιλών αποθετηρίων (για παράδειγμα, έργα από μεγάλους τεχνολογικούς οργανισμούς ή διαστημικές υπηρεσίες), παρατηρείται ότι τα αρχεία README τους συνήθως μοιράζονται έναν αριθμό κοινά μοτίβααν και κάθε έργο διατηρεί τη δική του οπτική και περιεχομενική ταυτότητα.

Είναι σύνηθες να βρίσκεις ένα σαφής τίτλος και πιθανή εικόνα εξωφύλλου (όπως ένα λογότυπο ή ένα banner για το έργο), ακολουθούμενο από μερικά σήματα που συνοψίζουν την κατάσταση του έργου, την άδεια χρήσης, την τρέχουσα έκδοση ή την κατάσταση δοκιμών. Στη συνέχεια, συνήθως υπάρχει ένα περιγραφή έργου, μια ενότητα σχετικά με την κατάσταση (σταθερή, υπό ανάπτυξη, πειραματική, κ.λπ.) και μια ενότητα με επιδείξεις ή στιγμιότυπα οθόνης.

Είναι επίσης πολύ συνηθισμένο να βρείτε ένα μπλοκ με πρόσβαση στο έργο (σύνδεσμοι προς την αναπτυγμένη έκδοση, τεκμηρίωση και δημοσιευμένα πακέτα), μια λίστα με τις τεχνολογίες που χρησιμοποιήθηκαν, ενότητες αφιερωμένες σε συνεισφέροντες, προγραμματιστές και, φυσικά, το άδειαΑυτά τα στοιχεία βοηθούν το README να λειτουργήσει τόσο ως ένας γρήγορος οδηγός για τους χρήστες όσο και ως επαγγελματική κάρτα για πιθανούς συνεισφέροντες.

Όσον αφορά τον σχεδιασμό, παρόλο που μιλάμε για αρχείο κειμένου, υπάρχει άφθονος χώρος για να γίνει πιο ευανάγνωστο: χρησιμοποιήστε καλά δομημένες επικεφαλίδες, ταξινομημένες και μη ταξινομημένες λίστες, πίνακες όπου χρειάζεται, και Έντονο κείμενο για την επισήμανση βασικών ιδεώνΣτο Markdown, μπορείτε επίσης να εισαγάγετε εικόνες, GIF και μικρά διακοσμητικά (όπως emoji) για να το κάνετε πιο φιλικό προς το χρήστη, έχοντας πάντα κατά νου τη σαφήνεια.

Ένα κόλπο που έχει συζητηθεί ελάχιστα είναι να γράφεις πάντα σκεπτόμενος κάποιον που Δεν γνωρίζει απολύτως τίποτα για το έργο.Αυτό σημαίνει αποφυγή υποθέσεων σχετικά με προηγούμενη γνώση, χρήση σαφούς και άμεσης γλώσσας και διευκρίνιση τεχνικών όρων την πρώτη φορά που εμφανίζονται. Και, φυσικά, ενημέρωση του README κάθε φορά που αλλάζει κάτι σχετικό στο έργο.

Άδεια, συνεισφορές και συγγραφή

Στα έργα ανοιχτού κώδικα, ένα ιδιαίτερα σημαντικό τμήμα του README είναι αυτό που είναι αφιερωμένο στο άδειαΗ δημοσίευση κώδικα σε ένα δημόσιο αποθετήριο δεν το καθιστά αυτόματα ελεύθερο λογισμικό. Είναι απαραίτητο να αναφέρεται ρητά υπό ποιες συνθήκες μπορεί να θεωρηθεί ελεύθερο λογισμικό. προς χρήση, τροποποίηση και αναδιανομή.

Η πιο συνηθισμένη πρακτική είναι η χρήση γνωστών αδειών χρήσης (MIT, Apache, GPL, Creative Commons για τεκμηρίωση, κ.λπ.) και η σύνδεση από το αρχείο README στο αρχείο LICENSE ή COPYING του αποθετηρίου. Με αυτόν τον τρόπο, κάθε ενδιαφερόμενος γνωρίζει αμέσως τι μπορεί να κάνει με τον κώδικα και ποιες είναι οι υποχρεώσεις του (για παράδειγμα, αναφορά, κοινή χρήση, περιορισμοί ευθύνης, κ.λπ.).

Ένα άλλο βασικό μπλοκ σε ένα ώριμο README είναι το οδηγός συνεισφορώνΑυτή η ενότητα εξηγεί πώς μπορούν να συνεισφέρουν και άλλοι στο έργο: οδηγίες στυλ, τη διαδικασία υποβολής αιτημάτων έλξης, τον τρόπο αναφοράς σφαλμάτων, ποιοι τύποι συνεισφορών γίνονται δεκτοί και πού συντονίζεται η εργασία. Μερικές φορές αυτές οι πληροφορίες περιέχονται σε ξεχωριστό αρχείο CONTRIBUTING.md που συνδέεται από το README.

Είναι επίσης καλή πρακτική να κάνετε ορατό το άτομα που συνεισφέρουν και προγραμματιστέςΟρισμένα έργα περιλαμβάνουν πίνακες με avatar και ονόματα που συνδέονται με τα προφίλ τους, ενώ άλλα απλώς απαριθμούν τους κύριους χρήστες. Αυτή η χειρονομία όχι μόνο αναγνωρίζει την εργασία, αλλά διευκολύνει και την άμεση επαφή εάν κάποιος χρειάζεται να μιλήσει με ένα συγκεκριμένο μέλος της ομάδας.

Τέλος, αξίζει να αφιερώσουμε μερικές γραμμές για να εξηγήσουμε πώς να λάβετε βοήθεια Και ποια κανάλια υπάρχουν: Θέματα GitHub, φόρουμ, λίστες αλληλογραφίας, συνομιλίες κ.λπ. Εάν το έργο δεν προσφέρει επίσημη υποστήριξη, είναι επίσης έγκυρο να το αναφέρετε σαφώς για να αποφευχθούν παρεξηγήσεις.

Με όλα τα παραπάνω, το αρχείο README γίνεται κεντρικό κομμάτι οποιουδήποτε ψηφιακού έργου: Εξηγεί τι είναι, πώς λειτουργεί, ποιος το συντηρεί και υπό ποιες συνθήκες μπορεί να χρησιμοποιηθεί.Η φροντίδα του περιεχομένου σας και η διατήρησή του ενημερωμένου είναι μια μικρή επένδυση που κάνει μεγάλη διαφορά στον τρόπο με τον οποίο οι άλλοι άνθρωποι αντιλαμβάνονται και χρησιμοποιούν την εργασία σας.