Γεια σου, Χαμπρ! Το όνομά μου είναι Lesha, είμαι αναλυτής συστημάτων για μια από τις ομάδες προϊόντων της Alfa-Bank. Τώρα αναπτύσσω μια νέα ηλεκτρονική τράπεζα για νομικά πρόσωπα και μεμονωμένους επιχειρηματίες.
Και όταν είσαι αναλυτής, ειδικά σε ένα τέτοιο κανάλι, δεν μπορείς να φτάσεις πουθενά χωρίς τεκμηρίωση και στενή συνεργασία μαζί του. Και η τεκμηρίωση είναι κάτι που πάντα εγείρει πολλά ερωτηματικά. Γιατί δεν περιγράφεται η διαδικτυακή εφαρμογή; Γιατί η προδιαγραφή υποδεικνύει πώς πρέπει να λειτουργεί η υπηρεσία, αλλά δεν λειτουργεί καθόλου έτσι; Γιατί μόνο δύο άτομα, εκ των οποίων ο ένας το έγραψε, μπορούν να καταλάβουν τις προδιαγραφές;
Ωστόσο, η τεκμηρίωση δεν μπορεί να αγνοηθεί για προφανείς λόγους. Και για να κάνουμε τη ζωή μας πιο εύκολη, αποφασίσαμε να αξιολογήσουμε την ποιότητα της τεκμηρίωσης. Πώς ακριβώς το κάναμε αυτό και σε ποια συμπεράσματα καταλήξαμε είναι κάτω από την περικοπή.
Ποιότητα τεκμηρίωσης
Για να μην επαναλάβω το "New Internet Bank" αρκετές δεκάδες φορές στο κείμενο, θα γράψω NIB. Τώρα έχουμε περισσότερες από δώδεκα ομάδες που εργάζονται για την ανάπτυξη του NIB για επιχειρηματίες και νομικά πρόσωπα. Επιπλέον, καθένα από αυτά είτε δημιουργεί τη δική του τεκμηρίωση για μια νέα υπηρεσία ή εφαρμογή web από την αρχή, είτε κάνει αλλαγές στην τρέχουσα. Με αυτήν την προσέγγιση, μπορεί η τεκμηρίωση καταρχήν να είναι υψηλής ποιότητας;
Και για να προσδιορίσουμε την ποιότητα της τεκμηρίωσης, έχουμε εντοπίσει τρία κύρια χαρακτηριστικά.
- Πρέπει να είναι πλήρης. Αυτό ακούγεται μάλλον σαν καπετάνιος, αλλά είναι σημαντικό να σημειωθεί. Θα πρέπει να περιγράφει λεπτομερώς όλα τα στοιχεία της εφαρμοσμένης λύσης.
- Πρέπει να είναι σχετικό. Δηλαδή, αντιστοιχούν στην τρέχουσα εφαρμογή της ίδιας της λύσης.
- Θα πρέπει να είναι κατανοητό. Έτσι ώστε το άτομο που το χρησιμοποιεί να καταλάβει πώς ακριβώς εφαρμόζεται η λύση.
Συνοψίζοντας - πλήρης, ενημερωμένη και κατανοητή τεκμηρίωση.
Опрос
Για να αξιολογήσουμε την ποιότητα της τεκμηρίωσης, αποφασίσαμε να πάρουμε συνέντευξη από αυτούς που συνεργάζονται άμεσα με αυτήν: αναλυτές NIB. Ζητήθηκε από τους ερωτηθέντες να αξιολογήσουν 10 δηλώσεις σύμφωνα με το σχήμα «Σε κλίμακα από το 1 έως το 5 (διαφωνώ πλήρως - συμφωνώ απόλυτα).»
Οι δηλώσεις αντανακλούσαν τα χαρακτηριστικά της ποιοτικής τεκμηρίωσης και τη γνώμη των συντακτών της έρευνας σχετικά με τα έγγραφα NIB.
- Η τεκμηρίωση για τις εφαρμογές NIB είναι ενημερωμένη και πλήρως συνεπής με την εφαρμογή τους.
- Η υλοποίηση των εφαρμογών NIB είναι πλήρως τεκμηριωμένη.
- Τεκμηρίωση για εφαρμογές NIB απαιτείται μόνο για λειτουργική υποστήριξη.
- Η τεκμηρίωση για τις εφαρμογές NIB είναι τρέχουσα κατά τη στιγμή της υποβολής τους για λειτουργική υποστήριξη.
- Οι προγραμματιστές εφαρμογών NIB χρησιμοποιούν τεκμηρίωση για να κατανοήσουν τι πρέπει να εφαρμόσουν.
- Υπάρχει αρκετή τεκμηρίωση για να κατανοήσουν οι εφαρμογές NIB πώς υλοποιούνται.
- Ενημερώνω αμέσως την τεκμηρίωση για τα έργα NIB εάν οριστικοποιηθούν (από την ομάδα μου).
- Οι προγραμματιστές εφαρμογών NIB εξετάζουν την τεκμηρίωση.
- Έχω ξεκάθαρη κατανόηση του τρόπου προετοιμασίας τεκμηρίωσης για έργα NIB.
- Καταλαβαίνω πότε πρέπει να γράφω/ενημερώνω τεκμηρίωση για έργα NIB.
Είναι σαφές ότι η απλή απάντηση "Από το 1 έως το 5" ενδέχεται να μην αποκαλύψει τις απαραίτητες λεπτομέρειες, επομένως ένα άτομο θα μπορούσε να αφήσει ένα σχόλιο για κάθε στοιχείο.
Όλα αυτά τα κάναμε μέσω του εταιρικού Slack - απλώς στείλαμε μια πρόσκληση σε αναλυτές συστημάτων να συμμετάσχουν σε μια έρευνα. Υπήρχαν 15 αναλυτές (9 από τη Μόσχα και 6 από την Αγία Πετρούπολη). Μετά την ολοκλήρωση της έρευνας, δημιουργήσαμε μια μέση βαθμολογία για καθεμία από τις 10 δηλώσεις, την οποία στη συνέχεια τυποποιήσαμε.
Να τι έγινε.
Η έρευνα έδειξε ότι, αν και οι αναλυτές τείνουν να πιστεύουν ότι η εφαρμογή των εφαρμογών NIB είναι πλήρως τεκμηριωμένη, δεν συμφωνούν ξεκάθαρα (0.2). Ως συγκεκριμένο παράδειγμα, επεσήμαναν ότι ορισμένες βάσεις δεδομένων και ουρές από υπάρχουσες λύσεις δεν καλύπτονταν από τεκμηρίωση. Ο προγραμματιστής μπορεί να πει στον αναλυτή ότι δεν είναι όλα τεκμηριωμένα. Αλλά η θέση ότι οι προγραμματιστές εξετάζουν την τεκμηρίωση δεν έλαβε επίσης σαφή υποστήριξη (0.33). Παραμένει, δηλαδή, ο κίνδυνος ελλιπούς περιγραφής των εφαρμοσμένων λύσεων.
Η συνάφεια είναι ευκολότερη - αν και δεν υπάρχει και πάλι σαφής συμφωνία (0,13), οι αναλυτές εξακολουθούν να τείνουν να θεωρούν την τεκμηρίωση σχετική. Τα σχόλια μας επέτρεψαν να καταλάβουμε ότι τα προβλήματα με τη συνάφεια είναι πιο συχνά στο μπροστινό μέρος παρά στη μέση. Ωστόσο, δεν μας έγραψαν τίποτα για την υποστήριξη.
Όσο για το αν οι ίδιοι οι αναλυτές καταλαβαίνουν πότε είναι απαραίτητο να γράψουν και να ενημερώσουν την τεκμηρίωση, η συμφωνία ήταν πολύ πιο ενιαία (1,33), συμπεριλαμβανομένου του σχεδιασμού της (1.07). Αυτό που επισημάνθηκε εδώ ως ταλαιπωρία ήταν η έλλειψη ενιαίων κανόνων για τη διατήρηση της τεκμηρίωσης. Επομένως, για να μην ενεργοποιηθεί η λειτουργία "Ποιος πηγαίνει στο δάσος, ποιος παίρνει καυσόξυλα", πρέπει να εργαστούν με βάση παραδείγματα υπάρχουσας τεκμηρίωσης. Ως εκ τούτου, μια χρήσιμη επιθυμία είναι να δημιουργηθεί ένα πρότυπο για τη διαχείριση εγγράφων και να αναπτυχθούν πρότυπα για τα μέρη τους.
Η τεκμηρίωση για τις εφαρμογές NIB είναι τρέχουσα κατά τη στιγμή της υποβολής για λειτουργική υποστήριξη (0.73). Αυτό είναι κατανοητό, διότι ένα από τα κριτήρια για την υποβολή ενός έργου για λειτουργική υποστήριξη είναι η ενημερωμένη τεκμηρίωση. Αρκεί επίσης να κατανοήσουμε την υλοποίηση (0.67), αν και μερικές φορές παραμένουν ερωτήματα.
Αλλά αυτό με το οποίο δεν συμφώνησαν οι ερωτηθέντες (εντελώς ομόφωνα) ήταν ότι η τεκμηρίωση για εφαρμογές NIB, κατ' αρχήν, χρειάζεται μόνο για λειτουργική υποστήριξη (-1.53). Οι αναλυτές αναφέρονται συχνότερα ως καταναλωτές τεκμηρίωσης. Η υπόλοιπη ομάδα (προγραμματιστές) - πολύ λιγότερο συχνά. Επιπλέον, οι αναλυτές πιστεύουν ότι οι προγραμματιστές δεν χρησιμοποιούν τεκμηρίωση για να κατανοήσουν τι πρέπει να εφαρμόσουν, αν και όχι ομόφωνα (-0.06). Αυτό, παρεμπιπτόντως, αναμένεται επίσης σε συνθήκες όπου η ανάπτυξη κώδικα και η σύνταξη τεκμηρίωσης προχωρούν παράλληλα.
Ποια είναι η ουσία και γιατί χρειαζόμαστε αυτούς τους αριθμούς;
Για να βελτιώσουμε την ποιότητα των εγγράφων, αποφασίσαμε να κάνουμε τα εξής:
- Ζητήστε από τον προγραμματιστή να ελέγξει γραπτά έγγραφα.
- Εάν είναι δυνατόν, ενημερώστε την τεκμηρίωση εγκαίρως, πρώτα μπροστά.
- Δημιουργήστε και υιοθετήστε ένα πρότυπο για την τεκμηρίωση έργων NIB, έτσι ώστε όλοι να μπορούν γρήγορα να κατανοήσουν ποια στοιχεία συστήματος και πώς ακριβώς πρέπει να περιγράφονται. Λοιπόν, αναπτύξτε τα κατάλληλα πρότυπα.
Όλα αυτά θα συμβάλουν στην αύξηση της ποιότητας των εγγράφων σε ένα νέο επίπεδο.
Τουλάχιστον έτσι ελπίζω.
Πηγή: www.habr.com