Τεκμηρίωση έργου

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

Μια ωραία εισαγωγή για καλά προετοιμασμένη τεκμηρίωση έργου μπορείτε να βρείτε στους οδηγούς του github: https://guides.github.com/features/wikis/. Αυτό δηλώνει ότι "το README θα πρέπει να περιέχει μόνο τις απαραίτητες πληροφορίες για τους προγραμματιστές ώστε να ξεκινήσουν να χρησιμοποιούν και να συνεισφέρουν στο έργο".

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

Γρήγορη εισαγωγή

- Τίτλος έργου: αυτό είναι απαραίτητο για κάθε README.

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

- Περιγραφή: να συμπεριλάβετε μερικές προτάσεις σχετικά με το έργο για να περιγράψετε γρήγορα τον κύριο σκοπό και τι κάνει.

Πίνακας περιεχομένων

Ένας κατάλογος περιεχομένων μπορεί να είναι χρήσιμος για μεγάλα αρχεία τεκμηρίωσης, αλλά αν το README σας είναι αρκετά συνοπτικό, τότε δεν είναι απαραίτητο.

Γενικές πληροφορίες

- Τμήμα Πληροφορίες: αυτή θα πρέπει να είναι μια πιο λεπτομερής περιγραφή του έργου - μπορεί να περιλαμβάνει πληροφορίες σχετικά με τους χρήστες, τους ρόλους τους, κάποιες πιο περίπλοκες περιπτώσεις, καθώς και στιγμιότυπα οθόνης κ.λπ.

- Μακέτες: ένα μέρος για συνδέσμους σε πηγές μακέτας UI/UX, αν υπάρχουν.

• Άλλες πληροφορίες όπως Πρόσβαση σε διακομιστές ή Ενσωμάτωση με εξωτερικά API: Παραδείγματα περιλαμβάνουν μια διεύθυνση url ενός staging instance, κοινά μη ευαίσθητα (!) διαπιστευτήρια πρόσβασης, συνδέσμους προς την τεκμηρίωση, κάποιες οδηγίες, κ.λπ.

Εγκατάσταση

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

- Εγκατάσταση: οδηγίες βήμα προς βήμα που πρέπει να ακολουθήσετε για να ξεκινήσετε το έργο.

- Ρυθμίσεις: περιγράφουν πού αποθηκεύονται οι τοπικές ρυθμίσεις και παρέχουν οδηγίες για το πώς μπορείτε να λάβετε τις δικές σας ρυθμίσεις.

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

Ανάπτυξη

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

Ανάπτυξη

Παρέχετε σαφείς οδηγίες βήμα προς βήμα για κάθε περιβάλλον και όλα όσα είναι "καλό να γνωρίζετε" κατά την εγκατάσταση.

Άλλες ιδέες για ξεχωριστά τμήματα

- Τεκμηρίωση API

- Changelog

- Εξωτερικοί πόροι: ένα μέρος για κάθε είδους συνδέσμους που μπορεί να είναι χρήσιμοι.

- Στοίβα εφαρμογών: μια λίστα της στοίβας εφαρμογών που χρησιμοποιούμε στο έργο - μπορεί να περιέχει μια σύντομη περιγραφή και το όνομα του παρόχου.

Ομάδα

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

Λίγα τελευταία λόγια

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

Και κάτι ακόμα: οι "οδηγίες" είναι το κλειδί, γι' αυτό γράψτε τις συχνά. Σας ευχαριστώ!

Διαβάστε περισσότερα:

• Αρχή "ανοικτό-κλειστό". Πρέπει ποτέ να τη χρησιμοποιήσω;
• Πώς να γράψετε έναν καλό και ποιοτικό κώδικα;
• 1TP57Ημερολόγιο. Ένα νέο έργο του Codest που βασίζεται στο Vue.js