Η τεκμηρίωση αποτελεί ουσιαστικό μέρος του κύκλου ανάπτυξης λογισμικού. Εξηγεί τον τρόπο χρήσης του λογισμικού και μπορεί να περιλαμβάνει οδηγούς χρήσης, αναφορές API, οδηγίες εγκατάστασης και σημειώσεις έκδοσης.
Η αυτοματοποίηση της τεκμηρίωσής σας είναι η πιο πρόσφατη τάση, καθώς μπορεί να βοηθήσει στην εξοικονόμηση χρόνου, στη μείωση των σφαλμάτων και στη διασφάλιση της συνέπειας. Η διατήρηση της τεκμηρίωσής σας ενημερωμένη και προσβάσιμη σε όλα τα ενδιαφερόμενα μέρη διευκολύνει τη συνεργασία και τη συνεχή βελτίωση.
Τα Έγγραφα ως κώδικας είναι μια προσέγγιση στον αυτοματισμό τεκμηρίωσης που αντιμετωπίζει την τεχνική τεκμηρίωση ως κώδικα.
Τι είναι τα Έγγραφα ως Κώδικας;
Το Docs as code είναι μια φιλοσοφία ανάπτυξης λογισμικού που βλέπει την τεχνική τεκμηρίωση ως μια μορφή κώδικα. Προτείνει ότι θα πρέπει να αντιμετωπίζετε την τεκμηρίωση με την ίδια αυστηρότητα και διαδικασία όπως ο κώδικας λογισμικού.
Η ιδέα πίσω από τα έγγραφα ως κώδικας είναι να αντιμετωπίζεται η τεκμηρίωση ως πρώτης τάξεως τεχνούργημα της διαδικασίας ανάπτυξης, ενσωματώνοντάς την με τον κύκλο ζωής του λογισμικού. Αυτό σημαίνει ότι αντιμετωπίζεται η τεκμηρίωση ως αναπόσπαστο μέρος της βάσης κωδικών. Σημαίνει ότι εφαρμόζετε σε αυτό τον ίδιο έλεγχο έκδοσης, συνεχή ενσωμάτωση και δοκιμές που κάνετε στον ίδιο τον κώδικα.
Σε ένα τυπικό έγγραφο ως ρύθμιση κώδικα, γράφετε την τεκμηρίωση σε αρχεία απλού κειμένου, συνήθως σε μια ελαφριά γλώσσα σήμανσης όπως η Markdown, HTML ή reStructuredText. Στη συνέχεια, το αποθηκεύετε στο ίδιο αποθετήριο με τον πηγαίο κώδικα. Αυτό καθιστά εύκολη τη διαχείριση και την παρακολούθηση αλλαγών τόσο στο λογισμικό όσο και στην τεκμηρίωση. Βοηθά επίσης να διασφαλιστεί ότι η τεκμηρίωση είναι ενημερωμένη με την πιο πρόσφατη έκδοση του κώδικα.
Γιατί πρέπει να χρησιμοποιείτε τα Έγγραφα ως κώδικα
Πριν τα έγγραφα ως κώδικας, η τεκμηρίωση συχνά αντιμετωπίζονταν ως ξεχωριστή από τον κώδικα, που δημιουργήθηκε με διαφορετικά εργαλεία και διαδικασίες. Αυτή η πιο χαλαρή προσέγγιση οδηγούσε συχνά σε ξεπερασμένη τεκμηρίωση και ασυνέπειες με τον κώδικα. Μπορείτε να αξιοποιήσετε πολλά πλεονεκτήματα υιοθετώντας τα έγγραφα ως προσέγγιση κώδικα.
Βελτιωμένη συνεργασία
Τα Έγγραφα ως κώδικας επιτρέπουν τη συνεργασία μεταξύ προγραμματιστών, τεχνικών συγγραφέων και άλλων ενδιαφερόμενων μερών στη διαδικασία ανάπτυξης. Δεδομένου ότι το αποθετήριο κώδικα φιλοξενεί την τεκμηρίωση, είναι εύκολο για διαφορετικά μέρη να συνεισφέρουν και να κάνουν αλλαγές. Αυτό βοηθά να διασφαλιστεί ότι η τεκμηρίωση είναι ακριβής, ενημερωμένη και ολοκληρωμένη.
Μια συνεργατική προσέγγιση στην τεκμηρίωση βοηθά να διασφαλιστεί ότι περιλαμβάνει όλες τις σχετικές πληροφορίες και ότι αντικατοπτρίζει με ακρίβεια το σύστημα λογισμικού όπως ερμηνεύεται από όλα τα μέρη.
Αυτοματισμός Διαδικασιών και Προσβασιμότητα
Ένα άλλο πλεονέκτημα των εγγράφων ως κώδικα είναι ότι επιτρέπει σε αυτοματοποιημένα εργαλεία να δημιουργούν και να δημοσιεύουν τεκμηρίωση. Ένα σύστημα κατασκευής μπορεί να δημιουργήσει αυτόματα εκδόσεις HTML ή PDF της τεκμηρίωσης από αρχεία απλού κειμένου για δημοσίευση σε έναν ιστότοπο ή μια εσωτερική πύλη τεκμηρίωσης. Αυτό καθιστά την τεκμηρίωση προσβάσιμη σε περισσότερα ενδιαφερόμενα μέρη.
Με την αυτοματοποίηση της διαδικασίας δημιουργίας και δημοσίευσης τεκμηρίωσης, τα έγγραφα ως κώδικας συμβάλλουν στη μείωση του χρόνου και της προσπάθειας που απαιτείται για τη διατήρηση και τη δημοσίευση της τεκμηρίωσης. Επιτρέπει στις ομάδες ανάπτυξης να επικεντρωθούν στη βελτίωση του λογισμικού.
Έλεγχος έκδοσης
Η αποθήκευση της τεκμηρίωσης στο ίδιο αποθετήριο κώδικα με το λογισμικό καθιστά εύκολη τη διαχείριση και την παρακολούθηση αλλαγών και στα δύο.
Μπορείς να χρησιμοποιήσεις συστήματα ελέγχου έκδοσης όπως το Git για να παρακολουθείτε τις αλλαγές τεκμηρίωσης και να επαναφέρετε τις προηγούμενες εκδόσεις εάν είναι απαραίτητο. Αυτό σας βοηθά να διασφαλίσετε ότι η τεκμηρίωση είναι ακριβής και ενημερωμένη και μπορείτε να εντοπίσετε και να ελέγξετε τις αλλαγές.
Τα τυπικά έγγραφα ως ροή εργασίας κώδικα
Τα τυπικά έγγραφα ως ροή εργασίας κώδικα περιλαμβάνουν τη σύνταξη, τον έλεγχο έκδοσης, τη δημιουργία και τη φιλοξενία:
Η διαδικασία της συγγραφής
Η διαδικασία γραφής είναι το πρώτο στάδιο μιας τυπικής ροής εργασιών εγγράφων ως κώδικα. Πλέον τεχνικούς συγγραφείς και οι μηχανικοί τεκμηρίωσης χρησιμοποιούν απλά MarkDown, AsciiDoc ή HTML. Γράφουν την τεκμηρίωση χρησιμοποιώντας εργαλεία όπως το GitBook και το Redocly που εξασφαλίζουν μια ομαλή διαδικασία.
Έλεγχος έκδοσης για τεκμηρίωση
Η τεκμηρίωση εξελίσσεται καθώς εξελίσσεται ο κώδικας. Θα χρειαστείτε ένα εξελιγμένο σύστημα ελέγχου έκδοσης όπως το Git, το Plastic SCM ή το Subversion για να παρακολουθείτε τις αλλαγές τεκμηρίωσης για ευκολότερη συνεργασία και παρακολούθηση εκδόσεων.
Η διαδικασία δημιουργίας τεκμηρίωσης
Η διαδικασία κατασκευής περιλαμβάνει την επεξεργασία και τη σύνταξη της τεκμηρίωσης στις μορφές παράδοσης. Αυτά μπορεί να είναι HTML, PDF, EPUB ή άλλα. Η διαδικασία τεκμηρίωσης γίνεται συνήθως ευκολότερη χρησιμοποιώντας γεννήτριες στατικών τοποθεσιών όπως οι Hugo και Jekyll.
Φιλοξενία και Διανομή Τεκμηρίωσης
Η διαδικασία φιλοξενίας ή διανομής είναι συνήθως το τελευταίο βήμα των εγγράφων ως διαδικασία κωδικοποίησης. Αυτή η διαδικασία διασφαλίζει ότι η τεκμηρίωση παραδίδεται στον τελικό χρήστη και είναι διαθέσιμη σε όλα τα ενδιαφερόμενα μέρη. Μπορείτε να χρησιμοποιήσετε σελίδες GitHub ή GitLab ή μια προσαρμοσμένη πύλη για να διανείμετε την τεκμηρίωσή σας στον Ιστό.
Μπορείτε να αυτοματοποιήσετε την τεκμηρίωση Go και Java χρησιμοποιώντας το GoDoc και το JavaDoc
Τα έγγραφα ως φιλοσοφία κώδικα φέρνουν επανάσταση στη συγγραφή και διαχείριση τεχνικής τεκμηρίωσης.
Πολλές γλώσσες προγραμματισμού, συμπεριλαμβανομένων των Go και Java, παρέχουν εργαλεία για την αυτοματοποίηση της τεκμηρίωσης χρησιμοποιώντας σχόλια κώδικα. Το Go παρέχει το εργαλείο Godoc και η Java παρέχει το JavaDoc.
