Πώς να χρησιμοποιήσεις generative AI για να φτιάχνεις καλύτερες τεχνικές τεκμηριώσεις

τεχνικές τεκμηριώσεις: Πώς να χρησιμοποιείς generative AI

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

Τυπικές προκλήσεις στην τεχνική τεκμηρίωση

Πριν δούμε πώς βοηθά το generative AI, αξίζει να θυμηθούμε κάποια κλασικά προβλήματα

• τεκμηρίωση που γράφεται τελευταία στιγμή, λίγο πριν το release
• κείμενα αντιγραμμένα από παλιές εκδόσεις, γεμάτα ανακρίβειες
• έλλειψη συνοχής στο ύφος και στη δομή ανάμεσα σε διαφορετικές ενότητες
• παραδείγματα κώδικα που δεν ταιριάζουν με το πραγματικό API
• έγγραφα που είναι δυσνόητα για junior προγραμματιστές ή χρήστες

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

Χρήση generative AI για πρώτο draft

Ενα από τα πιο πρακτικά σενάρια είναι να χρησιμοποιείς generative AI για τη δημιουργία πρώτου προσχεδίου σε διάφορα είδη τεκμηρίωσης

• περιγραφές κλάσεων, συναρτήσεων και modules με βάση σχόλια ή type hints
• σύνοψη της λειτουργίας ενός API endpoint από το request και το response schema
• εισαγωγικά κείμενα για κεφάλαια τεκμηρίωσης ή σελίδες overview

Ροή εργασίας

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

Με αυτόν τον τρόπο κερδίζεις χρόνο στο στήσιμο του σκελετού και εστιάζεις στην ουσία και στις λεπτομέρειες.

Βελτίωση ύφους και αναγνωσιμότητας

Ακόμη και όταν η τεκμηρίωση υπάρχει ήδη, μπορεί να είναι δύσκολη στην ανάγνωση. Το generative AI μπορεί να βοηθήσει σε

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

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

Παραδείγματα κώδικα και use cases

Η καλή τεκμηρίωση δεν σταματά στην περιγραφή των παραμέτρων. Χρειάζεται παραδείγματα κώδικα και πραγματικά use cases. Εδώ το generative AI μπορεί

• να δημιουργήσει βασικά snippets κώδικα που δείχνουν πώς χρησιμοποιείται μια συνάρτηση ή ένα endpoint
• να προτείνει παραλλαγές για συχνά σενάρια χρήσης
• να μετατρέψει παραδείγματα από μία γλώσσα σε άλλη, διατηρώντας τη λογική

Ενημέρωση τεκμηρίωσης όταν αλλάζει ο κώδικας

Ενα άλλο δυνατό σημείο είναι η βοήθεια στην ενημέρωση τεκμηρίωσης όταν γίνονται αλλαγές στο repository. Για παράδειγμα

• συγκρίνεις δύο εκδόσεις ενός αρχείου και ζητάς από το AI να σου περιγράψει συνοπτικά τις διαφορές σε φυσική γλώσσα
• του δίνεις το changelog ή τα pull request descriptions και ζητάς να ενημερώσει συγκεκριμένες ενότητες τεκμηρίωσης
• χρησιμοποιείς το AI για να προτείνει ποιες σελίδες documentation πιθανόν επηρεάζονται από συγκεκριμένες αλλαγές

Ετσι μειώνεται ο κίνδυνος να κυκλοφορούν παλιές οδηγίες την ώρα που ο κώδικας έχει ήδη προχωρήσει.

Δομή, πίνακες περιεχομένων και ιεράρχηση

Πολλές φορές δυσκολευόμαστε όχι στο ίδιο το κείμενο, αλλά στη δομή. Το generative AI μπορεί να προτείνει

• προτεινόμενο πίνακα περιεχομένων για ένα εγχειρίδιο ή για την τεκμηρίωση μιας βιβλιοθήκης
• λογική ροή από υψηλού επιπέδου overview προς πιο λεπτομερείς ενότητες
• ομαδοποίηση endpoints ή modules σε θεματικές ενότητες αντί για απλή αλφαβητική λίστα

Μπορείς να δώσεις στο εργαλείο μια λίστα από functions, αρχεία ή endpoints και να του ζητήσεις προτάσεις για το πώς θα έβλεπε την τεκμηρίωση ένας νέος χρήστης.

Πολυγλωσσική τεκμηρίωση

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

• γρήγορη μετάφραση υπαρχόντων σελίδων σε άλλη γλώσσα
• προσαρμογή όρων και παραδειγμάτων στο εκάστοτε κοινό
• έλεγχος συνέπειας ορολογίας ανάμεσα σε διαφορετικές γλώσσες

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

Περιορισμοί και κίνδυνοι

Παρότι τα οφέλη είναι σημαντικά, υπάρχουν και σαφείς περιορισμοί

• το μοντέλο μπορεί να εφεύρει λειτουργίες ή παραμέτρους που δεν υπάρχουν, αν δεν έχεις δώσει αρκετό context
• μπορεί να χρησιμοποιήσει παλιά patterns ή μη ασφαλείς πρακτικές αν βασίζεται σε γενικά δεδομένα εκπαίδευσης
• αν δεν προσέξεις, μπορεί να διαρρεύσουν ευαίσθητες πληροφορίες μέσα από prompts ή παραδείγματα κώδικα

Για αυτό

• δίνε πάντα στο AI όσο δυνατόν πιο συγκεκριμένο context από τον τρέχοντα κώδικα και τα schemas σου
• απόφυγε να βάζεις ευαίσθητα μυστικά σε prompts
• πέρασε όλη την παραγόμενη τεκμηρίωση από τεχνικό και, όπου χρειάζεται, νομικό έλεγχο

Σχεδιασμός workflow με AI στον κύκλο τεκμηρίωσης

Για να αξιοποιήσεις ουσιαστικά generative AI στην τεχνική τεκμηρίωση, είναι καλό να το εντάξεις συνειδητά στον κύκλο εργασιών σου

• πρώτο draft με AI, έλεγχος και βελτίωση από εσένα
• χρήση AI για αναδιατύπωση και βελτίωση παλιών σελίδων
• βοήθεια σε παραδείγματα κώδικα, αλλά με tests και manual verification
• χρήση AI για αναζήτηση ασυνεπειών ή κενών ανάμεσα σε κώδικα και documentation