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