Περιεχόμενο

• Βήματα
• Συμβουλές
• Απαραίτητα υλικά

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

Βήματα

Μέθοδος 1 από 2: Σύνταξη τεκμηρίωσης λογισμικού για τεχνικούς χρήστες

1. 

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

2. 

   
   
   Αποφασίστε πόση τεκμηρίωση πρέπει να βρίσκεται στον κώδικα προγράμματος και πόσο πρέπει να διαχωρίζεται από αυτήν. Όσο πιο τεχνική τεκμηρίωση αναπτύχθηκε μέσα στην πηγή του προγράμματος, τόσο πιο εύκολο θα είναι η ενημέρωση και η συντήρηση του κώδικα, καθώς και η τεκμηρίωση των διαφόρων εκδόσεων της αρχικής εφαρμογής. Τουλάχιστον, η τεκμηρίωση στον πηγαίο κώδικα πρέπει να εξηγεί το σκοπό των συναρτήσεων, των υπορουτίνων, των μεταβλητών και των σταθερών.
   • Εάν ο πηγαίος κώδικας είναι ιδιαίτερα μεγάλος, μπορεί να τεκμηριωθεί με τη μορφή αρχείου βοήθειας, το οποίο μπορεί να ευρετηριαστεί ή να αναζητηθεί με λέξεις-κλειδιά. Αυτό είναι ένα ιδιαίτερο πλεονέκτημα για εφαρμογές όπου η λογική του προγράμματος είναι κατακερματισμένη σε πολλές σελίδες και περιλαμβάνει πολλά συμπληρωματικά αρχεία, καθώς και με ορισμένες εφαρμογές ιστού.
   • Ορισμένες γλώσσες προγραμματισμού, όπως Java και .NET Framework (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, εάν η τεκμηρίωση απαιτεί πολλά στιγμιότυπα οθόνης. Όπως και με άλλα έγγραφα, αυτά τα στιγμιότυπα οθόνης πρέπει να συμπεριληφθούν για να σας βοηθήσουν να εξηγήσετε πώς λειτουργεί το πρόγραμμα και όχι να εντυπωσιάσετε τον χρήστη.
• Ο τόνος είναι ιδιαίτερα σημαντικός, ειδικά όταν γράφετε τεκμηρίωση για τελικούς χρήστες. Καλέστε τους "εσείς" αντί για "χρήστες".

Απαραίτητα υλικά

• Εργαλείο τεκμηρίωσης λογισμικού / αρχεία βοήθειας
• Εργαλείο δημιουργίας στιγμιότυπου οθόνης