Καλές πρακτικές για την ανάπτυξη ελεύθερου και ανοικτού λογισμικού: Τεκμηρίωση

Τεκμηρίωση: Καλές πρακτικές για την ανάπτυξη ελεύθερου και ανοιχτού λογισμικού

Τεκμηρίωση: Καλές πρακτικές για την ανάπτυξη ελεύθερου και ανοιχτού λογισμικού

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

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

Καλές πρακτικές: Τεκμηρίωση - Εισαγωγή

Επιπλέον, στη συγκεκριμένη περίπτωση του Η τεκμηρίωση του Ελεύθερου Λογισμικού είναι ζωτικής σημασίας, δεδομένου ότι επιτρέπει την πλήρη εγγύηση του μεταφορά γνώσης και ενδυνάμωση απαραίτητο για την ικανοποιητική εκπλήρωση του 4 ελευθερίες προωθείται από αυτήν, οι οποίες είναι:

  • 0: Η ελευθερία εκτέλεσης του προγράμματος όσο θέλετε, για οποιονδήποτε σκοπό.
  • 1: Η ελευθερία πρόσβασης και μελέτης ενός προγράμματος και η αλλαγή ή προσαρμογή του προς όφελός σας.
  • 2: Η ελευθερία να μοιράζεστε ή να αναδιανέμετε αντίγραφα για να διαδώσετε το ίδιο ή / και να βοηθήσετε άλλους.
  • 3: Η ελευθερία διανομής αντιγράφων των τροποποιημένων εκδόσεών σας σε τρίτους.

Μια καλή τεκμηρίωση επιτρέπει, επομένως, το δημιουργημένο προϊόν:

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

Ορθές πρακτικές: Τεκμηρίωση - Readme

Καλές πρακτικές: Τεκμηρίωση

Βασικά στοιχεία

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

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

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

Καλές πρακτικές σχετικά με την τεκμηρίωση σε αρχεία κειμένου README

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

Για το άρθρο μας, έχουμε λάβει το Βέλτιστες Πρακτικές σχεδιάστηκε και αποκαλύφθηκε από το "Κώδικας για αναπτυξιακή πρωτοβουλία" del Διαμερικανική Τράπεζα Ανάπτυξης, η οποία συνοπτικά μας λέει ότι η καλή τεκμηρίωση βασίζεται σε ένα αρχείο κειμένου README.md (ή .txt) Πρέπει να δομηθεί ως εξής:

Συνιστώμενη δομή αρχείων README

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

σε αυτές ορθών πρακτικών, προτείνουν επίσης την προσθήκη στο Τεκμηρίωση αρχείου README για να γίνει πιο ολοκληρωμένο, οι ακόλουθες ενότητες:

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

Για να επεκτείνετε αυτές τις πληροφορίες, στο Βέλτιστες Πρακτικές σε θέματα της τεκμηρίωση για την ανάπτυξη του ελεύθερο λογισμικό, από το "Κώδικας για αναπτυξιακή πρωτοβουλία" del Διαμερικανική Τράπεζα Ανάπτυξης μπορείτε να κάνετε κλικ στον παρακάτω σύνδεσμο: Τεκμηρίωση - Οδηγός για τη δημοσίευση ψηφιακών εργαλείων. Και σε άλλες δημοσιεύσεις θα διερευνήσουμε το μέρος που αναφέρεται ορθών πρακτικών στο αξιολόγηση και αδειοδότηση del Ελεύθερο και ανοιχτό λογισμικό τους εαυτούς τους.

Συμπέρασμα

Συμπέρασμα

Ελπίζουμε ότι αυτό "χρήσιμη μικρή ανάρτηση" σχετικά με το «Buenas prácticas» στο πεδίο των «documentación» για δημιουργία κατά την ανάπτυξη «Software libre y abierto», να έχει μεγάλο ενδιαφέρον και χρησιμότητα, για το σύνολο «Comunidad de Software Libre y Código Abierto» και μεγάλη συμβολή στη διάδοση του υπέροχου, γιγαντιαίου και αναπτυσσόμενου οικοσυστήματος εφαρμογών και για «GNU/Linux».

Και για περισσότερες πληροφορίες, μην διστάσετε πάντα να επισκεφθείτε κανένα Διαδικτυακή βιβλιοθήκη ως OpenLibra y jedit να διαβασω βιβλία (PDF) σχετικά με αυτό το θέμα ή άλλα τομείς γνώσης. Προς το παρόν, αν σας άρεσε αυτό «publicación», μην σταματήσετε να το μοιράζεστε με άλλους, στο δικό σας Αγαπημένοι ιστότοποι, κανάλια, ομάδες ή κοινότητες κοινωνικών δικτύων, κατά προτίμηση δωρεάν και ανοιχτό ως Μαστόδονταςή ασφαλές και ιδιωτικό Telegram.

Ή απλώς επισκεφτείτε την αρχική μας σελίδα στο DesdeLinux ή εγγραφείτε στο επίσημο κανάλι Τηλεγράφημα από DesdeLinux για να διαβάσετε και να ψηφίσετε για αυτό ή άλλες ενδιαφέρουσες δημοσιεύσεις «Software Libre», «Código Abierto», «GNU/Linux» και άλλα θέματα που σχετίζονται με «Informática y la Computación», Και «Actualidad tecnológica».


Γίνε ο πρώτος που θα σχολιάσει

Αφήστε το σχόλιό σας

Η διεύθυνση email σας δεν θα δημοσιευθεί. Τα υποχρεωτικά πεδία σημειώνονται με *

*

*

  1. Υπεύθυνος για τα δεδομένα: Miguel Ángel Gatón
  2. Σκοπός των δεδομένων: Έλεγχος SPAM, διαχείριση σχολίων.
  3. Νομιμοποίηση: Η συγκατάθεσή σας
  4. Κοινοποίηση των δεδομένων: Τα δεδομένα δεν θα κοινοποιούνται σε τρίτους, εκτός από νομική υποχρέωση.
  5. Αποθήκευση δεδομένων: Βάση δεδομένων που φιλοξενείται από τα δίκτυα Occentus (ΕΕ)
  6. Δικαιώματα: Ανά πάσα στιγμή μπορείτε να περιορίσετε, να ανακτήσετε και να διαγράψετε τις πληροφορίες σας.