Η τεκμηρίωση λογισμικού είναι απλώς μια συλλογή άρθρων. Αλλά ακόμα και αυτοί μπορούν να σας ξεσηκώσουν. Στην αρχή αφιερώνεις αρκετή ώρα αναζητώντας τις απαραίτητες οδηγίες. Τότε βγάζεις νόημα στο ακατανόητο κείμενο. Κάνετε όπως γράφετε, αλλά το πρόβλημα δεν λύνεται. Ψάχνεις άλλο άρθρο, νευριάζεις... Μια ώρα μετά τα παρατάς όλα και φεύγεις. Έτσι λειτουργεί η κακή τεκμηρίωση. Τι την κάνει να αρέσει και πώς να το διορθώσετε - διαβάστε παρακάτω.
Υπήρχαν πολλές ελλείψεις στην παλιά μας τεκμηρίωση. Το επαναλαμβάνουμε εδώ και σχεδόν ένα χρόνο, ώστε το σενάριο που περιγράφεται παραπάνω να μην επηρεάσει τους πελάτες μας. Ματιά, и .
Πρόβλημα 1. Ασαφή, κακώς γραμμένα άρθρα
Εάν η τεκμηρίωση είναι αδύνατο να κατανοηθεί, ποιο είναι το νόημα; Κανείς όμως δεν γράφει επίτηδες ακατανόητα άρθρα. Συμβαίνουν όταν ο συγγραφέας δεν σκέφτεται το κοινό και τον στόχο, απλώς ρίχνει νερό και δεν ελέγχει το κείμενο για λάθη.
- Το κοινό. Πριν γράψετε ένα άρθρο, πρέπει να σκεφτείτε το επίπεδο προετοιμασίας του αναγνώστη. Είναι λογικό σε ένα άρθρο για αρχάριους να μην παρακάμπτετε βασικά βήματα και να αφήνετε τεχνικούς όρους χωρίς εξήγηση και σε ένα άρθρο για ένα σπάνιο χαρακτηριστικό που χρειάζονται μόνο οι επαγγελματίες, να μην εξηγείτε την έννοια της λέξης PHP.
- στόχος. Ένα άλλο πράγμα που είναι καλύτερο να σκεφτείτε εκ των προτέρων. Ο συγγραφέας πρέπει να θέσει έναν ξεκάθαρο στόχο, να καθορίσει το χρήσιμο αποτέλεσμα του άρθρου και να αποφασίσει τι θα κάνει ο αναγνώστης αφού το διαβάσει. Εάν αυτό δεν γίνει, το αποτέλεσμα θα είναι μια περιγραφή για χάρη της περιγραφής.
- Νερό και ζωύφια. Πολλές περιττές πληροφορίες και γραφειοκρατική ορολογία, λάθη και τυπογραφικά λάθη παρεμβαίνουν στην αντίληψη. Ακόμα κι αν ο αναγνώστης δεν είναι γραμματικός ναζί, η απροσεξία στο κείμενο μπορεί να τον απενεργοποιήσει.
Λάβετε υπόψη τις παραπάνω συμβουλές και τα άρθρα θα γίνουν πιο ξεκάθαρα - εγγυημένα. Για να το κάνετε ακόμα καλύτερο, εκμεταλλευτείτε το δικό μας .
Πρόβλημα 2: Τα άρθρα δεν απαντούν σε όλες τις ερωτήσεις
Είναι κακό όταν η τεκμηρίωση δεν συμβαδίζει με την ανάπτυξη, δεν απαντά σε πραγματικές ερωτήσεις και τα λάθη σε αυτήν δεν διορθώνονται για χρόνια. Αυτά δεν είναι τόσο προβλήματα του συγγραφέα, αλλά μάλλον η οργάνωση των διαδικασιών εντός της εταιρείας.
Η τεκμηρίωση δεν συμβαδίζει με την εξέλιξη
Το χαρακτηριστικό είναι ήδη σε κυκλοφορία, το μάρκετινγκ σχεδιάζει να το καλύψει και, στη συνέχεια, αποδεικνύεται ότι δεν υπάρχει ακόμα νέο άρθρο ή μετάφραση στην τεκμηρίωση. Έπρεπε ακόμη και να αναβάλουμε την κυκλοφορία εξαιτίας αυτού. Μπορείτε να ζητήσετε από όλους να παραδώσουν εργασίες σε τεχνικούς συγγραφείς εγκαίρως όσο θέλετε, αλλά δεν θα λειτουργήσει. Εάν η διαδικασία δεν είναι αυτοματοποιημένη, η κατάσταση θα επαναληφθεί.
Κάναμε αλλαγές στο YouTrack. Το έργο της συγγραφής ενός άρθρου σχετικά με ένα νέο χαρακτηριστικό ανατίθεται σε έναν τεχνικό συγγραφέα την ίδια στιγμή που αρχίζει να δοκιμάζεται το χαρακτηριστικό. Ταυτόχρονα, το μάρκετινγκ το μαθαίνει για να προετοιμαστεί για προώθηση. Οι ειδοποιήσεις έρχονται επίσης στον εταιρικό αγγελιοφόρο Mattermost, επομένως είναι απλά αδύνατο να χάσετε νέα από προγραμματιστές.
Η τεκμηρίωση δεν αντικατοπτρίζει τα αιτήματα των χρηστών
Έχουμε συνηθίσει να δουλεύουμε έτσι: βγήκε ένα χαρακτηριστικό, το συζητήσαμε. Περιέγραψε πώς να το ενεργοποιήσετε, να το απενεργοποιήσετε και να κάνετε λεπτές ρυθμίσεις. Τι γίνεται όμως αν ο πελάτης χρησιμοποιεί το λογισμικό μας με τρόπο που δεν περιμέναμε; Ή κάνει λάθη που δεν τα έχουμε σκεφτεί;
Για να διασφαλίσετε ότι η τεκμηρίωση είναι όσο το δυνατόν πληρέστερη, συνιστούμε να αναλύσετε αιτήματα υποστήριξης, ερωτήσεις σε θεματικά φόρουμ και ερωτήματα στις μηχανές αναζήτησης. Τα πιο δημοφιλή θέματα θα μεταβιβαστούν σε τεχνικούς συγγραφείς, ώστε να μπορούν να συμπληρώνουν υπάρχοντα άρθρα ή να γράφουν νέα.
Η τεκμηρίωση δεν βελτιώνεται
Είναι δύσκολο να το κάνεις τέλεια αμέσως. θα υπάρξουν ακόμα λάθη. Μπορείτε να ελπίζετε σε σχόλια από τους πελάτες, αλλά είναι απίθανο να αναφέρουν κάθε τυπογραφικό λάθος, ανακρίβεια, ασαφές ή μη ευρεθέν άρθρο. Εκτός από τους πελάτες, οι υπάλληλοι διαβάζουν την τεκμηρίωση, πράγμα που σημαίνει ότι βλέπουν τα ίδια σφάλματα. Αυτό μπορεί να χρησιμοποιηθεί! Πρέπει απλώς να δημιουργήσουμε συνθήκες στις οποίες θα είναι εύκολο να αναφέρουμε ένα πρόβλημα.
Έχουμε μια ομάδα στην εσωτερική μας πύλη όπου οι εργαζόμενοι αφήνουν σχόλια, προτάσεις και ιδέες για τεκμηρίωση. Η υποστήριξη χρειάζεται ένα άρθρο, αλλά δεν υπάρχει; Ο ελεγκτής παρατήρησε ανακρίβεια; Ο συνεργάτης παραπονέθηκε στους υπεύθυνους ανάπτυξης για τα λάθη; Όλοι σε αυτήν την ομάδα! Οι τεχνικοί συγγραφείς διορθώνουν κάποια πράγματα αμέσως, μεταφέρουν κάποια πράγματα στο YouTrack και λαμβάνουν υπόψη κάποια πράγματα. Για να διατηρήσουμε το θέμα ζωντανό, υπενθυμίζουμε κατά καιρούς στους ανθρώπους την ύπαρξη της ομάδας και τη σημασία της ανατροφοδότησης.
Πρόβλημα 3. Χρειάζεται πολύς χρόνος για να βρείτε το άρθρο που χρειάζεστε
Ένα άρθρο που δεν μπορεί να βρεθεί δεν είναι καλύτερο από ένα άρθρο που δεν υπάρχει. Το σύνθημα της καλής τεκμηρίωσης θα πρέπει να είναι «Εύκολο στην αναζήτηση, εύκολο στην εύρεση». Πώς να το πετύχετε αυτό;
Οργανώστε τη δομή και καθορίστε την αρχή της επιλογής θεμάτων. Η δομή πρέπει να είναι όσο το δυνατόν πιο διαφανής, έτσι ώστε ο αναγνώστης να μην αναρωτιέται, "Πού μπορώ να βρω αυτό το άρθρο;" Συνοψίζοντας, υπάρχουν δύο προσεγγίσεις: από τη διεπαφή και από τις εργασίες.
- Από τη διεπαφή. Το περιεχόμενο αντιγράφει τις ενότητες του πίνακα. Αυτό συνέβαινε στην παλιά τεκμηρίωση του συστήματος ISP.
- Από τα καθήκοντα. Οι τίτλοι των άρθρων και των ενοτήτων αντικατοπτρίζουν τα καθήκοντα των χρηστών. Οι τίτλοι περιέχουν σχεδόν πάντα ρήματα και απαντήσεις στην ερώτηση «πώς να το κάνουμε». Περνάμε τώρα σε αυτή τη μορφή.
Όποια προσέγγιση κι αν επιλέξετε, βεβαιωθείτε ότι το θέμα είναι σχετικό με τις ανάγκες του χρήστη και καλύπτεται με τρόπο που θα απαντά με ακρίβεια στην ερώτηση του χρήστη.
Ρυθμίστε μια κεντρική αναζήτηση. Σε έναν ιδανικό κόσμο, η αναζήτηση θα πρέπει να λειτουργεί ακόμα και όταν κάνετε τυπογραφικό λάθος ή γλωσσικό λάθος. Η αναζήτησή μας στο Confluence δεν μπορεί να μας ευχαριστήσει ακόμα με αυτό. Εάν έχετε πολλά προϊόντα και η τεκμηρίωση είναι κοινή, προσαρμόστε την αναζήτηση στη σελίδα στην οποία βρίσκεται ο χρήστης. Στην περίπτωσή μας, η αναζήτηση στην κύρια σελίδα λειτουργεί για όλα τα προϊόντα και αν βρίσκεστε ήδη σε μια συγκεκριμένη ενότητα, τότε μόνο για τα άρθρα σε αυτήν.
Προσθέστε περιεχόμενο και φρυγανιά. Είναι καλό όταν κάθε σελίδα έχει ένα μενού και ψίχουλα - τη διαδρομή του χρήστη στην τρέχουσα σελίδα με τη δυνατότητα επιστροφής σε οποιοδήποτε επίπεδο. Στην παλιά τεκμηρίωση του συστήματος ISP, έπρεπε να βγείτε από το άρθρο για να φτάσετε στο περιεχόμενο. Ήταν άβολο, οπότε το φτιάξαμε στο νέο.
Τοποθετήστε συνδέσμους στο προϊόν. Εάν οι άνθρωποι έρχονται να υποστηρίξουν ξανά και ξανά με την ίδια ερώτηση, είναι λογικό να προσθέσετε μια υπόδειξη με τη λύση του στη διεπαφή. Εάν έχετε δεδομένα ή κατανοείτε πότε ένας χρήστης αντιμετωπίζει πρόβλημα, μπορείτε επίσης να τον ειδοποιήσετε μέσω email. Θα δείξετε ανησυχία και θα αφαιρέσετε το βάρος από την υποστήριξη.
Στα δεξιά στο αναδυόμενο παράθυρο υπάρχει ένας σύνδεσμος προς ένα άρθρο σχετικά με τη ρύθμιση του DNSSEC στην ενότητα διαχείρισης τομέα ISPmanager
Ρύθμιση παραπομπών εντός της τεκμηρίωσης. Άρθρα που σχετίζονται μεταξύ τους θα πρέπει να «συνδέονται». Εάν τα άρθρα σας είναι σε μια σειρά, φροντίστε να προσθέσετε βέλη προς τα εμπρός και προς τα πίσω στο τέλος κάθε κειμένου.
Πιθανότατα, ένα άτομο θα πάει πρώτα σε μια μηχανή αναζήτησης για να αναζητήσει απάντηση στην ερώτησή του, όχι σε εσάς. Θα ήταν κρίμα αν δεν υπήρχαν σύνδεσμοι με την τεκμηρίωση εκεί για τεχνικούς λόγους. Φροντίστε λοιπόν για τη βελτιστοποίηση μηχανών αναζήτησης.
Πρόβλημα 4. Η ξεπερασμένη διάταξη εμποδίζει την αντίληψη
Εκτός από τα κακώς κείμενα, η τεκμηρίωση μπορεί επίσης να καταστραφεί από το σχέδιο. Ο κόσμος έχει συνηθίσει να διαβάζει καλοσχεδιασμένο υλικό. Blogs, κοινωνικά δίκτυα, μέσα ενημέρωσης - όλο το περιεχόμενο παρουσιάζεται όχι μόνο όμορφα, αλλά και βολικά για ανάγνωση, ευχάριστο στο μάτι. Επομένως, είναι εύκολο να κατανοήσουμε τον πόνο ενός ατόμου που βλέπει κείμενο όπως στο παρακάτω στιγμιότυπο οθόνης.
Υπάρχουν τόσα πολλά στιγμιότυπα οθόνης και επισημάνσεις σε αυτό το άρθρο που δεν βοηθούν, αλλά εμποδίζουν μόνο την αντίληψη (η εικόνα μπορεί να κάνει κλικ)
Δεν χρειάζεται να μετατρέψετε την τεκμηρίωση σε μια μακροχρόνια μελέτη με πολλά εφέ, αλλά πρέπει να ληφθούν υπόψη οι βασικοί κανόνες.
Σχέδιο. Καθορίστε το πλάτος, τη γραμματοσειρά, το μέγεθος, τις επικεφαλίδες και τις εσοχές του σώματος του κειμένου. Συμμετάσχετε έναν σχεδιαστή και για να αποδεχτείτε το έργο ή να αντεπεξέλθετε μόνοι σας, διαβάστε το βιβλίο του Artem Gorbunov «Τυπογραφία και διάταξη». Παρουσιάζει μόνο μία άποψη διάταξης, αλλά είναι αρκετά επαρκής.
Απαλλαγή. Προσδιορίστε τι απαιτεί έμφαση στο κείμενο. Συνήθως πρόκειται για μια διαδρομή στη διεπαφή, κουμπιά, ένθετα κώδικα, αρχεία διαμόρφωσης, μπλοκ "Παρακαλώ σημειώστε". Προσδιορίστε ποια θα είναι τα κύρια σημεία αυτών των στοιχείων και καταγράψτε τα στους κανονισμούς. Λάβετε υπόψη ότι όσο λιγότερη απόρριψη, τόσο το καλύτερο. Όταν υπάρχουν πολλά, το κείμενο γίνεται «θορυβώδες». Ακόμη και τα εισαγωγικά δημιουργούν θόρυβο αν χρησιμοποιούνται πολύ συχνά.
Στιγμιότυπα. Συμφωνήστε με την ομάδα σας σε ποιες περιπτώσεις χρειάζονται στιγμιότυπα οθόνης. Σίγουρα δεν χρειάζεται να απεικονίζεται κάθε βήμα. Ένας μεγάλος αριθμός στιγμιότυπων οθόνης, συμ. μεμονωμένα κουμπιά παρεμβαίνουν στην αντίληψη και αλλοιώνουν τη διάταξη. Προσδιορίστε το μέγεθος και τη μορφή των επισημάνσεων και των υπογραφών στα στιγμιότυπα οθόνης και καταγράψτε τα στους κανονισμούς. Να θυμάστε ότι οι εικόνες πρέπει πάντα να ταιριάζουν με αυτό που γράφεται και να είναι σχετικές. Και πάλι, εάν το προϊόν ενημερώνεται τακτικά, θα είναι δύσκολο να παρακολουθείτε το καθένα.
Μήκος κειμένου. Αποφύγετε τα υπερβολικά μεγάλα άρθρα. Διαλύστε τα ή αν αυτό δεν είναι δυνατό, προσθέστε έναν πίνακα περιεχομένων με συνδέσμους αγκύρωσης στην αρχή του άρθρου. Ένας απλός τρόπος για να κάνετε ένα άρθρο οπτικά πιο σύντομο είναι να αποκρύψετε τεχνικές λεπτομέρειες που χρειάζονται ένας στενός κύκλος αναγνωστών κάτω από ένα spoiler.
Μορφές. Συνδυάστε διάφορες μορφές στα άρθρα σας: κείμενο, βίντεο και εικόνες. Αυτό θα βελτιώσει την αντίληψη.
Μην προσπαθείτε να καλύψετε προβλήματα με όμορφες διατάξεις. Ειλικρινά, εμείς οι ίδιοι ελπίζαμε ότι το "περιτύλιγμα" θα σώσει την ξεπερασμένη τεκμηρίωση, αλλά δεν λειτούργησε. Τα κείμενα περιείχαν τόσο πολύ οπτικό θόρυβο και περιττές λεπτομέρειες που οι κανονισμοί και ο νέος σχεδιασμός ήταν ανίσχυροι.
Πολλά από αυτά που περιγράφονται παραπάνω θα καθοριστούν από την πλατφόρμα που χρησιμοποιείτε για την τεκμηρίωση. Για εμάς, για παράδειγμα, είναι το Confluence. Έπρεπε να τα βάλω κι εγώ μαζί του. Εάν ενδιαφέρεστε, διαβάστε την ιστορία του προγραμματιστή ιστού μας: .
Από πού να αρχίσετε να βελτιώνεστε και πώς να επιβιώσετε
Εάν η τεκμηρίωσή σας είναι τόσο μεγάλη όσο αυτή του συστήματος ISP και δεν ξέρετε από πού να ξεκινήσετε, ξεκινήστε με τα μεγαλύτερα προβλήματα. Οι πελάτες δεν καταλαβαίνουν το έγγραφο - εργάζονται για τη βελτίωση των κειμένων, τη δημιουργία κανονισμών, την εκπαίδευση συγγραφέων. Η τεκμηρίωση είναι ξεπερασμένη - εστίαση σε εσωτερικές διαδικασίες. Ξεκινήστε με τα πιο δημοφιλή άρθρα σχετικά με τα προϊόντα με τη μεγαλύτερη ζήτηση: ζητήστε υποστήριξη, δείτε αναλυτικά στοιχεία ιστότοπου και ερωτήματα αναζήτησης.
Ας πούμε αμέσως - δεν θα είναι εύκολο. Και είναι απίθανο να συμβεί γρήγορα. Εκτός κι αν μόλις ξεκινάς και το κάνεις σωστά την πρώτη φορά. Ένα πράγμα που γνωρίζουμε με βεβαιότητα είναι ότι θα βελτιωθεί με τον καιρό. Αλλά η διαδικασία δεν θα τελειώσει ποτέ :-).
Πηγή: www.habr.com
