Οδηγός εγχειριδίου χρήσης

Αυτός ο οδηγός είναι προσαρμογή του The Good Docs Project’s how-to guide. Χρησιμοποιήστε αυτόν τον οδηγό για να συμπληρώσετε κάθε ενότητα του πρότυπου οδηγού χρήσης how-to template.

Εισαγωγή

Ένα εγχειρίδιο καθοδηγεί τους χρήστες σας μέσα από μια σειρά βημάτων που απαιτούνται στην επίλυση ενός συγκεκριμένου προβλήματος. Τους δείχνει πώς να λύσουν ένα πραγματικό πρόβλημα ή να ολοκληρώσουν μια εργασία χρησιμοποιώντας το Koha, όπως για παράδειγμα πώς να κλείσουν μια βιβλιοθήκη.

Σημείωση

Μια εργασία είναι μια ενέργεια που μπορούν να εκτελέσουν οι χρήστες σας με το Koha για να επιτύχουν έναν στόχο. Για την επίτευξη ενός στόχου μπορεί να απαιτούνται πολλαπλές εργασίες.

Ένα εγχειρίδιο χρήσης περιγράφει με σαφήνεια μια σειρά διαδοχικών βημάτων για την ολοκλήρωση μιας εργασίας. Το εγχειρίδιο χρήσης προϋποθέτει ότι ο χρήστης διαθέτει βασικές γνώσεις σχετικά με το Koha.

Τα εγχειρίδια χρήσης συχνά συγχέονται με τους οδηγούς εκμάθησης tutorials. Τα εγχειρίδια χρήσης είναι προσανατολισμένα στις εργασίες, ενώ οι οδηγοί εκμάθησης είναι προσανατολισμένοι στη μάθηση. Οι διαφορές μεταξύ των δύο:

Οδηγός εκμα΄θησης	Εγχειρίδιο χρήσης
Εστιασμένο στη μάθηση: Βοηθά τους αρχάριους ή τους έμπειρους χρήστες να μάθουν μια νέα λειτουργία με πρακτικό τρόπο.	Προσανατολισμένο στην εργασία: Βοηθά έναν έμπειρο χρήστη να ολοκληρώσει μια εργασία ή να επιλύσει ένα πρόβλημα.
Ακολουθεί μια προσεκτικά σχεδιασμένη πορεία από την αρχή μέχρι το τέλος.	Στοχεύει σε ένα επιτυχημένο αποτέλεσμα και καθοδηγεί τον χρήστη με τον ασφαλέστερο και πιο σίγουρο τρόπο προς τον στόχο.
Εξαλείφει τυχόν απρόβλεπτα σενάρια και παρέχει στους χρήστες ένα επιτυχημένο αποτέλεσμα.	Εφιστά την προσοχή του χρήστη στην πιθανότητα απρόβλεπτων σεναρίων και τον καθοδηγεί σχετικά με τον τρόπο αντιμετώπισής τους.
Προϋποθέτει ότι οι χρήστες δεν διαθέτουν πρακτικές γνώσεις και πρέπει να αναφέρονται ρητά όλα τα εργαλεία, οι ρυθμίσεις των αρχείων, οι εννοιολογικές λεπτομέρειες κ.λπ.	Προϋποθέτει ότι οι χρήστες διαθέτουν πρακτικές γνώσεις.

Γιατί χρειάζομαι οδηγίες χρήσης;

Ένα εγχειρίδιο χρήσης χρησιμοποιείται συχνά για να βοηθήσει τους πεπειραμένους χρήστες να εκτελέσουν μια εργασία σωστά. Μπορεί:

• Παρουσιάζει τις δυνατότητες του Koha.

• Καθοδηγεί τους χρήστες σας να λύσουν ένα πραγματικό πρόβλημα με το Koha μέσω μιας σειράς βημάτων.

• Βοηθάει στην απάντηση συγκεκριμένων ερωτήσεων που ενδέχεται να έχουν οι χρήστες.

• Κάνει τους χρήστες να αισθάνονται άνετα με τη χρήση του Koha.

• Βελτιώνει την εμπειρία του χρήστη και συμβάλλει στη μείωση του κόστους, μειώνοντας τον αριθμό των αιτημάτων υποστήριξης.

Οι νέοι χρήστες μπορούν επίσης να επωφεληθούν από ένα εγχειρίδιο χρήσης, υπό την προϋπόθεση ότι το εγχειρίδιο είναι καλά γραμμένο και περιλαμβάνει όλες τις απαραίτητες γνώσεις που απαιτούνται για την ολοκλήρωση της εργασίας.

Πριν τη συγγραφή ενός οδηγού χρήσης

Πριν ξεκινήσετε να εργάζεστε για έναν οδηγό, προσδιορίστε:

• Το κύριο κοινό ή την περίπτωση χρήσης για το εγχειρίδιο.

• Τα διαφορετικά σενάρια που μπορεί να συναντήσουν οι χρήστες στον πραγματικό κόσμο κατά την ολοκλήρωση μιας εργασίας. Αν συμβαίνει αυτό, τότε θα συμβεί εκείνο. Στην περίπτωση του …, μια εναλλακτική προσέγγιση είναι να…

• Τον πιο σίγουρο και ασφαλή τρόπο για να ολοκληρωθεί μια εργασία. Προτείνοντας πολλαπλούς τρόπους για την ολοκλήρωση μιας εργασίας, ζητάτε από τους χρήστες να σκεφτούν τους διαφορετικούς τρόπους και να επιλέξουν. Εξοικονομήστε χρόνο και προσπάθεια στους χρήστες σας, εξαλείφοντας τις επιλογές.

• Τα πιθανά σενάρια που μπορεί να αντιμετωπίσει ένας χρήστης κατά την ολοκλήρωση μιας εργασίας και οι αντίστοιχες λύσεις τους.

Βέλτιστες πρακτικές για τη σύνταξη ενός οδηγού χρήσης

• Αναφέρετε έναν λογικό στόχο (εργασία) για κάθε οδηγία. Προσπαθήστε να αποφύγετε περιπτώσεις όπου μόνο ένα μέρος της οδηγίας είναι σχετικό με τον χρήστη.

• Προετοιμάστε τους χρήστες σας για το απροσδόκητο, προειδοποιήστε τους για την πιθανότητα εμφάνισής του και παρέχετε οδηγίες για τον τρόπο αντιμετώπισής του. Για παράδειγμα, συμπεριλάβετε επισημάνσεις όπως προειδοποιήσεις, προφυλάξεις ή σημειώσεις για να κοινοποιήσετε σημαντικές πληροφορίες κατά την ολοκλήρωση μιας εργασίας.

• Χρησιμοποιήστε υποθετικές προστακτικές. Αν θέλετε το x, κάντε το y. Για να επιτύχετε το w, κάντε το z.

• Μην εξηγείτε έννοιες.

• Μερικές φορές είναι χρήσιμο να παρέχετε περιστασιακά συνδέσμους προς υποστηρικτικά έγγραφα για περισσότερες πληροφορίες. Ιδιαίτερα όταν ο χρήστης μπορεί να χρειαστεί υποστηρικτικές πληροφορίες ή conceptual information and reference materials. Ωστόσο, αποφύγετε να παρέχετε πάρα πολλούς συνδέσμους μέσα στο εγχειρίδιο. Κρατήστε τους χρήστες σας σε μία μόνο σελίδα όσο το δυνατόν περισσότερο και παρέχετε συνδέσμους προς πρόσθετους πόρους στο κάτω μέρος της σελίδας.

• Αποφύγετε την υπερβολική τεκμηρίωση πολλαπλών τρόπων για την επίτευξη του ίδιου στόχου. Εάν υπάρχουν περισσότεροι από ένας τρόποι για την ολοκλήρωση ενός συγκεκριμένου στόχου, επιλέξτε και τεκμηριώστε τον πιο συνηθισμένο ή ενδεδειγμένο τρόπο ολοκλήρωσης του στόχου. Οι επιπλέον μέθοδοι πρέπει να παραλείπονται ή να αναφέρονται με την παροχή ενός συνδέσμου ή ενός εγγράφου αναφοράς.

• Βεβαιωθείτε πάντα ότι τα βήματα που παρέχονται στον οδηγό χρήσης είναι τεχνικά ακριβή. Δοκιμάστε τις οδηγίες χρήσης από την αρχή έως το τέλος, ώστε να εντοπίσετε τυχόν παραλείψεις, λανθασμένες λεπτομέρειες, βήματα σε λάθος σειρά και κενά πληροφοριών που εμποδίζουν τους χρήστες. Εάν δεν είναι δυνατό να το δοκιμάσετε μόνοι σας, ζητήστε από έναν προγραμματιστή, βιβλιοθηκονόμο ή ειδικό στο θέμα να σας δείξει τα βήματα και, αν είναι δυνατό, καταγράψτε τη συνεδρία.

• Επαναλάβετε τις οδηγίες μετά από κάθε σημαντική έκδοση του προϊόντος, για να βεβαιωθείτε ότι οι οδηγίες εξακολουθούν να είναι ακριβείς.

• Οι μακροσκελείς οδηγίες χρήσης μπορεί να καταβάλλουν τους χρήστες. Εστιάστε μόνο σε μία εργασία στην οδηγία χρήσης και περιορίστε την σε 8-10 βήματα το πολύ ανά εργασία. Εάν η εργασία είναι πολύ μεγάλη και περίπλοκη, χωρίστε την σε πολλές λογικές υπο-εργασίες με τα δικά τους βήματα.

Σχετικά με την ενότητα «Σύνοψη»

Χρησιμοποιήστε αυτήν την ενότητα για να παρέχετε:

• Μια σαφή περιγραφή του προβλήματος ή της εργασίας που μπορεί να λύσει ή να ολοκληρώσει ο χρήστης.

• Πότε και γιατί ο χρήστης σας μπορεί να θέλει να εκτελέσει την εργασία. Για παράδειγμα, σε έναν οδηγό για τη δημιουργία ενός αιτήματος εξαγωγής, μπορείτε να ενημερώσετε τους χρήστες ότι τα αιτήματα εξαγωγής χρησιμοποιούνται για να ενημερώσετε τους άλλους σχετικά με τις αλλαγές που έχετε προωθήσει σε έναν παράρτημα ενός αποθετηρίου.

Ο οδηγός προϋποθέτει ότι ο χρήστης έχει βασικές γνώσεις σχετικά με το Koha και γνωρίζει τι θέλει να επιτύχει.

Μερικά παραδείγματα:

• Αυτός ο οδηγός εξηγεί πώς να δημιουργήσετε ένα ερώτημα στο Bugzilla. Μπορείτε να δημιουργήσετε ερωτήματα για να παρακολουθείτε σφάλματα, βελτιώσεις και νέες λειτουργίες για τις ενότητες και τα εργαλεία του Koha.

• Αυτός ο οδηγός εξηγεί πώς να κλείσετε προσωρινά μια βιβλιοθήκη. Το προσωρινό κλείσιμο μιας βιβλιοθήκης μπορεί να απαιτεί την πραγματοποίηση αρκετών αλλαγών στο Koha, όπως η ενημέρωση του προσωπικού και των χρηστών, η ενημέρωση των ανακοινώσεων και η παράταση των ημερομηνιών λήξης των δανεισμών.

Σχετικά με την ενότητα «Πριν ξεκινήσετε»

{Αυτή η ενότητα είναι προαιρετική}

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

Χρησιμοποιήστε αυτήν την ενότητα για να κοινοποιήσετε τυχόν προαπαιτούμενα για αυτό το εγχειρίδιο, όπως:

• Την εξοικείωση με την ενότητα ή τη λειτουργία του Koha

• Οποιεσδήποτε πληροφορίες, λογισμικό ή εργαλεία που απαιτούνται

• Περιβάλλοντα για την εγκατάσταση και παραμετροποίηση

• Πληροφορίες πιστοποίησης και εξουσιοδότησης

• Άλλοι οδηγοί ή πληροφορίες για ανάγνωση

• Σύνδεσμοι προς διαδικασίες ή πληροφορίες, ή οποιεσδήποτε χρήσιμες οδηγίες σχετικά με τον τρόπο απόκτησης όσων χρειάζονται.

Για ευκολία στην κατανόηση, εξετάστε το ενδεχόμενο να ομαδοποιήσετε τις προϋποθέσεις σε κατηγορίες, όπως βασικές γνώσεις και προϋποθέσεις λογισμικού.

Προαιρετικά, παρέχετε ενδείξεις που υποδηλώνουν στον χρήστη ότι πιθανώς βρίσκεται σε λάθος σημείο και προσφέρετε πιο κατάλληλες επιλογές. Για παράδειγμα, εάν είστε χρήστης Linux, ανατρέξτε στο {σύνδεσμος προς τον σχετικό οδηγό χρήσης Linux}.

Παραδείγματα:

Before you begin, ensure you have:

* A conceptual understanding of RESTful APIs.

Before you begin, ensure you have:

* API credentials for the v3.5 API.
* Access to the Postman application.
* (Optional) A development environment (IDE) that displays API responses formatted for readability.

Σχετικά με την ενότητα «Βήματα»

Στην ενότητα «Βήματα» περιγράφετε τι πρέπει να κάνει ο χρήστης. Χρησιμοποιήστε μια οργανωμένη λίστα για να καταγράψετε τα βήματα. Το πρότυπο οργανώνει τα βήματα με τον ακόλουθο τρόπο:

{Task name}

{Optional: Provide a concise description of the purpose of this task. Only
include this if the purpose is not clear from the task title.}

1. {Write the action to take here. Start with a verb.}

   {Optional: Explanatory text}

   {Optional: Code sample or screenshot that helps your users complete this
   step}

   {Optional: Result}

   {Optional: If needed, you can add substeps below a primary step.}

Ένα παράδειγμα βήματος:

Create a pull request

Pull requests are used to inform others of changes you have pushed to a
branch in a repository. Once a pull request is opened, you can collaborate
with reviewers and make changes before merging into the base branch.

1. To create a pull request:

   1.1. Navigate to the main page of your repository.

   1.2. Under your repository name, click **Pull requests**. By default, all
   open pull requests are displayed.

Εάν συμπεριλαμβάνετε δείγματα κώδικα στα βήματά σας, βεβαιωθείτε ότι έχουν σωστή κατάταξη:

1. Ορίστε το όνομα χρήστη Git για το αποθετήριο σας.

   Μπορείτε να αλλάξετε το όνομα που σχετίζεται με τις υποβολές σας στο Git χρησιμοποιώντας την εντολή git config.

   git config user.name "Dakota Everson"
   

Συμβουλές για τη σύνταξη βημάτων

• Για τα ονόματα εργασιών, ξεκινήστε με ένα απλό ρήμα bare infinitive επίσης γνωστό ως απλό ρήμα ή base form. Για παράδειγμα, «connect», «set up» ή «build» και εκφράστε τον τίτλο ως μια ολοκληρωμένη σκέψη. Μην χρησιμοποιείτε τη μορφή -ing του ρήματος, επειδή είναι πιο δύσκολο να μεταφραστεί. Αντί να πείτε «Connect», μπορείτε να πείτε «Connect to the VM instance».

• Για κάθε βήμα, παρέχετε προαιρετικά κάποιες βασικές πληροφορίες σχετικά με την εργασία, ώστε οι χρήστες να γνωρίζουν τι πρόκειται να κάνουν και γιατί. Συνεχίζοντας με το παράδειγμα, μπορείτε να παρέχετε κάποιες βέλτιστες πρακτικές για τη δημιουργία ευκολομνημόνευτων ονομάτων αποθετηρίων.

• Προαιρετικά, προσθέστε ένα δείγμα κώδικα code sample <https://developers.google.com/style/code-samples>`_ ή screenshot μετά το επεξηγηματικό κείμενο, ανάλογα με τον τύπο του οδηγού που γράφετε. Τα στιγμιότυπα οθόνης είναι ένας εξαιρετικός τρόπος για να δείξετε συγκεκριμένα μέρη της οθόνης στα οποία αναφέρεστε σε ένα βήμα. Βεβαιωθείτε ότι τα δείγματα κώδικα λειτουργούν και είναι πάντα ενημερωμένα.

• Θυμηθείτε να καθοδηγείτε τους χρήστες σας καθώς τους εξηγείτε κάθε βήμα. Εάν πρέπει να ανοίξουν ένα συγκεκριμένο αρχείο ή παράθυρο διαλόγου για να ολοκληρώσουν την εργασία, δώστε τους πρώτα αυτή την πληροφορία.

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

• Χρησιμοποιήστε απλή γλώσσα και ορίστε κάθε τεχνικό όρο δίπλα σε αυτόν.

• Συμπεριλάβετε μόνο μία ενέργεια σε κάθε βήμα.

Για επιπλέον συμβουλές σχετικά με τη σύνταξη βημάτων, ανατρέξτε στη σύνταξη διαδικαστικών βημάτων writing procedural steps.

Σχετικά με την ενότητα «Δείτε επίσης»

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

Ένα παράδειγμα μπορεί να είναι η ρύθμιση ενός προγράμματος ηλεκτρονικού ταχυδρομείου, το οποίο απαιτεί διαπιστευτήρια λειτουργίας για μια ενεργή διεύθυνση ηλεκτρονικού ταχυδρομείου. Ο αναγνώστης δεν χρειάζεται να γνωρίζει πώς να εγκαταστήσει και να εκτελέσει τον διακομιστή ηλεκτρονικού ταχυδρομείου του για να αποκτήσει αυτή την πρόσβαση, αν και αυτό είναι πιθανώς χρήσιμο. Ο σύνδεσμος προς την τεκμηρίωση σχετικά με την εκτέλεση ενός τοπικού διακομιστή ηλεκτρονικού ταχυδρομείου θα μπορούσε επομένως να συμπεριληφθεί στην ενότητα «Δείτε επίσης».

Πρόσθετες πηγές

• Bhatti, J., et.al. 2021. Docs for Developers: An Engineer’s Field Guide to Technical Writing 1st ed. Edition.

• Diátaxis. 2017. A systematic framework for technical documentation authoring.

• Carey, M., et.al. 2014. Developing Quality Technical Information: A Handbook for Writers and Editors.

• Google Developer’s Style Guide.

---

Περιηγηθείτε σε άλλους οδηγούς και πρότυπα στο The Good Docs Project.