Η καλή τεκμηρίωση λογισμικού, είτε πρόκειται για τεκμηρίωση προδιαγραφών για προγραμματιστές και δοκιμαστές, τεχνικά έγγραφα για εσωτερικούς χρήστες, είτε εγχειρίδια και αρχεία βοήθειας για τελικούς χρήστες, θα βοηθήσει τους χρήστες να κατανοήσουν τις δυνατότητες και τις λειτουργίες του λογισμικού. Η καλή τεκμηρίωση είναι η τεκμηρίωση που είναι συγκεκριμένη, σαφής και σχετική, με όλες τις πληροφορίες που χρειάζεται ο χρήστης. Αυτό το άρθρο θα σας καθοδηγήσει στη σύνταξη τεκμηρίωσης λογισμικού για τεχνικούς χρήστες και τελικούς χρήστες.
Βήμα
Μέθοδος 1 από 2: Σύνταξη τεκμηρίωσης λογισμικού για τεχνικούς χρήστες
Βήμα 1. Μάθετε ποιες πληροφορίες πρέπει να συμπεριλάβετε
Το έγγραφο προδιαγραφών χρησιμοποιείται ως εγχειρίδιο αναφοράς για σχεδιαστές διεπαφών, προγραμματιστές που γράφουν κώδικα και δοκιμαστές που επαληθεύουν την απόδοση του λογισμικού. Οι πληροφορίες που πρέπει να συμπεριληφθούν εξαρτώνται από το πρόγραμμα που δημιουργείται, αλλά ενδέχεται να περιλαμβάνουν τα ακόλουθα:
- Σημαντικά αρχεία στην εφαρμογή, όπως αρχεία που δημιουργήθηκαν από την ομάδα ανάπτυξης, βάσεις δεδομένων που έχουν πρόσβαση κατά την εκτέλεση του προγράμματος και εφαρμογές τρίτων.
- Λειτουργίες και υπορουτίνες, συμπεριλαμβανομένης εξήγησης για τη χρήση της τιμής συνάρτησης/υπορουτίνας, τιμών εισόδου και εξόδου.
- Μεταβλητές και σταθερές προγράμματος και πώς χρησιμοποιούνται.
- Συνολική δομή του προγράμματος. Για προγράμματα που βασίζονται σε μονάδα δίσκου, ίσως χρειαστεί να περιγράψετε κάθε ενότητα και βιβλιοθήκη. Or, εάν γράφετε ένα εγχειρίδιο για ένα πρόγραμμα που βασίζεται στον ιστό, ίσως χρειαστεί να εξηγήσετε ποια αρχεία χρησιμοποιεί κάθε σελίδα.
Βήμα 2. Αποφασίστε ποιο επίπεδο τεκμηρίωσης πρέπει να υπάρχει και να διαχωρίζεται από τον κώδικα του προγράμματος
Όσο πιο τεχνική τεκμηρίωση περιλαμβάνεται στον κώδικα του προγράμματος, τόσο πιο εύκολο θα είναι να τον ενημερώσετε και να τον διατηρήσετε, καθώς και να εξηγήσετε τις διάφορες εκδόσεις του προγράμματος. Τουλάχιστον, η τεκμηρίωση στον κώδικα προγράμματος θα πρέπει να περιλαμβάνει τη χρήση συναρτήσεων, υπορουτίνων, μεταβλητών και σταθερών.
- Εάν ο πηγαίος κώδικας είναι μεγάλος, μπορείτε να γράψετε τεκμηρίωση σε ένα αρχείο βοήθειας, το οποίο στη συνέχεια μπορεί να ευρετηριαστεί ή να αναζητηθεί με συγκεκριμένες λέξεις -κλειδιά. Τα ξεχωριστά αρχεία τεκμηρίωσης είναι χρήσιμα εάν η λογική του προγράμματος χωρίζεται σε πολλές σελίδες και περιλαμβάνει αρχεία υποστήριξης, όπως μια εφαρμογή ιστού.
- Ορισμένες γλώσσες προγραμματισμού (όπως Java, Visual Basic. NET ή C#) έχουν τα δικά τους πρότυπα τεκμηρίωσης κώδικα. Σε τέτοιες περιπτώσεις, ακολουθήστε την τυπική τεκμηρίωση που πρέπει να περιλαμβάνεται στον πηγαίο κώδικα.
Βήμα 3. Επιλέξτε το κατάλληλο εργαλείο τεκμηρίωσης
Σε ορισμένες περιπτώσεις, το εργαλείο τεκμηρίωσης καθορίζεται από τη γλώσσα προγραμματισμού που χρησιμοποιείται. Οι γλώσσες C ++, C#, Visual Basic, Java, PHP και άλλες έχουν τα δικά τους εργαλεία τεκμηρίωσης. Ωστόσο, εάν όχι, τα εργαλεία που χρησιμοποιούνται θα εξαρτηθούν από την απαιτούμενη τεκμηρίωση.
- Ένας επεξεργαστής κειμένου όπως το Microsoft Word είναι κατάλληλος για τη δημιουργία αρχείων κειμένου εγγράφου, αρκεί η τεκμηρίωση να είναι συνοπτική και απλή. Για τη δημιουργία μακράς τεκμηρίωσης με πολύπλοκο κείμενο, οι περισσότεροι τεχνικοί συγγραφείς επιλέγουν ένα εξειδικευμένο εργαλείο τεκμηρίωσης, όπως το Adobe FrameMaker.
- Τα αρχεία βοήθειας για την τεκμηρίωση του πηγαίου κώδικα μπορούν να δημιουργηθούν με ένα πρόγραμμα δημιουργίας αρχείων υποστήριξης, όπως το RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ή HelpLogix.
Μέθοδος 2 από 2: Σύνταξη τεκμηρίωσης λογισμικού για τελικούς χρήστες
Βήμα 1. Γνωρίστε τους επιχειρηματικούς λόγους που βασίζονται στη δημιουργία του εγχειριδίου
Ενώ ο κύριος λόγος για την τεκμηρίωση λογισμικού είναι να βοηθήσει τους χρήστες να κατανοήσουν πώς να χρησιμοποιούν την εφαρμογή, υπάρχουν αρκετοί άλλοι λόγοι που μπορεί να βασίζονται στη δημιουργία τεκμηρίωσης, όπως το να βοηθήσει το τμήμα μάρκετινγκ να πουλήσει την εφαρμογή, να βελτιώσει την εικόνα της εταιρείας και να μειώσει την τεχνική υποστήριξη δικαστικά έξοδα. Σε ορισμένες περιπτώσεις, απαιτείται τεκμηρίωση για συμμόρφωση με κανονισμούς ή άλλες νομικές απαιτήσεις.
Ωστόσο, η τεκμηρίωση δεν είναι ένα καλό υποκατάστατο μιας διεπαφής. Εάν μια εφαρμογή απαιτεί πολλή τεκμηρίωση για τη λειτουργία της, θα πρέπει να έχει σχεδιαστεί για να είναι πιο διαισθητική
Βήμα 2. Γνωρίστε το κοινό -στόχο της τεκμηρίωσης
Γενικά, οι χρήστες λογισμικού έχουν περιορισμένες γνώσεις υπολογιστών πέρα από τις εφαρμογές που χρησιμοποιούν. Υπάρχουν διάφοροι τρόποι για την κάλυψη των αναγκών τεκμηρίωσής τους:
- Δώστε προσοχή στον τίτλο του χρήστη λογισμικού. Για παράδειγμα, ο διαχειριστής συστήματος κατανοεί γενικά διάφορες εφαρμογές υπολογιστών, ενώ ο γραμματέας γνωρίζει μόνο τις εφαρμογές που χρησιμοποιεί για την εισαγωγή δεδομένων.
- Δώστε προσοχή στους χρήστες λογισμικού. Αν και οι θέσεις τους είναι γενικά συμβατές με τις εργασίες που εκτελούνται, αυτές οι θέσεις μπορεί να έχουν διαφορετικό φόρτο εργασίας, ανάλογα με τον τόπο της επιχείρησης. Συνεντεύγοντας πιθανούς χρήστες, μπορείτε να μάθετε εάν η εκτίμησή σας για τον τίτλο εργασίας τους είναι σωστή.
- Δώστε προσοχή στην υπάρχουσα τεκμηρίωση. Η τεκμηρίωση και οι προδιαγραφές λειτουργικότητας του λογισμικού μπορούν να δείξουν τι πρέπει να γνωρίζουν οι χρήστες για να τις χρησιμοποιήσουν. Ωστόσο, λάβετε υπόψη ότι οι χρήστες μπορεί να μην ενδιαφέρονται να μάθουν τα «εσωτερικά» του προγράμματος.
- Μάθετε τι χρειάζεται για να ολοκληρώσετε μια εργασία και τι χρειάζεται για να την ολοκληρώσετε.
Βήμα 3. Καθορίστε την κατάλληλη μορφή για την τεκμηρίωση
Η τεκμηρίωση λογισμικού μπορεί να οργανωθεί σε 1 ή 2 μορφές, συγκεκριμένα βιβλία αναφοράς και εγχειρίδια. Μερικές φορές, ο συνδυασμός των δύο μορφών είναι μια καλή λύση.
- Οι μορφές αναφοράς χρησιμοποιούνται για να περιγράψουν όλες τις δυνατότητες του λογισμικού, όπως κουμπιά, καρτέλες, πεδία και πλαίσια διαλόγου και πώς λειτουργούν. Ορισμένα αρχεία βοήθειας είναι γραμμένα σε αυτήν τη μορφή, ειδικά αυτά που είναι ευαίσθητα στο περιβάλλον. Όταν ο χρήστης κάνει κλικ στη Βοήθεια σε μια συγκεκριμένη οθόνη, ο χρήστης θα λάβει το σχετικό θέμα.
- Η χειροκίνητη μορφή χρησιμοποιείται για να εξηγήσει πώς να κάνετε κάτι με το λογισμικό. Τα εγχειρίδια είναι γενικά σε έντυπη ή PDF μορφή, αν και ορισμένες σελίδες βοήθειας περιλαμβάνουν επίσης οδηγίες για τον τρόπο με τον οποίο μπορείτε να κάνετε ορισμένα πράγματα. (Γενικά, οι χειροκίνητες μορφές δεν είναι ευαίσθητες στο περιβάλλον, αλλά ενδέχεται να συνδέονται από θέματα ευαίσθητα στο περιβάλλον). Τα εγχειρίδια έχουν γενικά τη μορφή οδηγού, με περίληψη των εργασιών που πρέπει να εκτελεστούν σε περιγραφή και οδηγό μορφοποιημένο σε βήματα.
Βήμα 4. Αποφασίστε για τον τύπο της τεκμηρίωσης
Η τεκμηρίωση λογισμικού για χρήστες μπορεί να είναι συσκευασμένη σε μία ή περισσότερες από τις ακόλουθες μορφές: έντυπα εγχειρίδια, αρχεία PDF, αρχεία βοήθειας ή ηλεκτρονική βοήθεια. Κάθε τύπος τεκμηρίωσης έχει σχεδιαστεί για να σας δείχνει πώς να χρησιμοποιείτε τις λειτουργίες του λογισμικού, είτε πρόκειται για οδηγό είτε για σεμινάριο. Η διαδικτυακή τεκμηρίωση και οι σελίδες βοήθειας μπορεί επίσης να περιλαμβάνουν βίντεο επίδειξης, κείμενο και στατικές εικόνες.
Τα διαδικτυακά αρχεία βοήθειας και υποστήριξης θα πρέπει να ευρετηριαστούν και να αναζητηθούν χρησιμοποιώντας λέξεις -κλειδιά, έτσι ώστε οι χρήστες να βρίσκουν γρήγορα τις πληροφορίες που χρειάζονται. Παρόλο που μια εφαρμογή δημιουργίας αρχείων βοήθειας μπορεί να δημιουργήσει ένα ευρετήριο αυτόματα, εξακολουθεί να συνιστάται η δημιουργία ενός ευρετηρίου με μη αυτόματο τρόπο χρησιμοποιώντας λέξεις -κλειδιά που αναζητούνται συνήθως
Βήμα 5. Επιλέξτε το κατάλληλο εργαλείο τεκμηρίωσης
Εκτυπωμένα εγχειρίδια ή PDF μπορούν να δημιουργηθούν με ένα πρόγραμμα επεξεργασίας κειμένου όπως το Word ή έναν προηγμένο επεξεργαστή κειμένου όπως το FrameMaker, ανάλογα με το μήκος και την πολυπλοκότητα του αρχείου. Τα αρχεία βοήθειας μπορούν να γραφτούν με ένα πρόγραμμα δημιουργίας αρχείων βοήθειας, όπως RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ή HelpServer.
Συμβουλές
- Το κείμενο της τεκμηρίωσης του προγράμματος πρέπει να είναι δομημένο με τέτοιο τρόπο ώστε να είναι ευανάγνωστο. Τοποθετήστε την εικόνα όσο το δυνατόν πιο κοντά στο κατάλληλο κείμενο. Αναλύστε την τεκμηρίωση κατά τμήματα και θέματα λογικά. Κάθε ενότητα ή θέμα πρέπει να περιγράφει ένα συγκεκριμένο πρόβλημα, τόσο τις εργασίες όσο και τις δυνατότητες του προγράμματος. Τα σχετικά θέματα μπορούν να εξηγηθούν με συνδέσμους ή λίστες αναφοράς.
- Κάθε ένα από τα εργαλεία τεκμηρίωσης που περιγράφονται σε αυτό το άρθρο μπορεί να συμπληρωθεί από ένα πρόγραμμα δημιουργίας στιγμιότυπων οθόνης, όπως το SnagIt εάν η τεκμηρίωσή σας απαιτεί πολλά στιγμιότυπα οθόνης. Όπως κάθε άλλη τεκμηρίωση, θα πρέπει επίσης να συμπεριλάβετε στιγμιότυπα οθόνης για να εξηγήσετε πώς λειτουργεί η εφαρμογή, αντί να «παρασύρετε» τον χρήστη.
- Η προσοχή στο στυλ είναι πολύ σημαντική, ειδικά αν γράφετε τεκμηρίωση λογισμικού για τελικούς χρήστες. Απευθυνθείτε στους χρήστες με την αντωνυμία "εσείς", αντί για "χρήστης".
