Γενικές οδηγίες σύνταξης

Ακολουθήστε αυτές τις οδηγίες συγγραφής όταν δημιουργείτε περιεχόμενο χρησιμοποιώντας τα πρότυπα του The Good Docs Project.

Γλώσσα και ύφος

• Χρησιμοποιήστε σταθερή γλώσσα, ορθογραφία και ύφος σε όλα τα έγγραφά σας.

• Περιγράψτε τα πράγματα όσο το δυνατόν σαφέστερα και με ακρίβεια.

• Ελέγξτε το κείμενό σας με ένα πρόγραμμα ελέγχου γραμματικής linter για να δείτε πόσο ευανάγνωστο είναι.

  • Εργαλεία όπως το Grammarly σας βοηθούν να εντοπίσετε γραμματικά λάθη

  • Εργαλεία όπως το Vale σας βοηθούν να εντοπίσετε προβλήματα στυλ.

  • Αυτό το άρθρο περιλαμβάνει μια λίστα με άλλα εργαλεία linter.)

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

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

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

Σύνταξη διαδικαστικών βημάτων

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

• Για διαδικασίες με πολλά βήματα, εξετάστε το ενδεχόμενο να χωρίσετε το περιεχόμενο σε υποενότητες των 5-10 βημάτων. Αυτό καθιστά τις πληροφορίες ευκολότερες στην ανάγνωση και την απομνημόνευση και δίνει στον αναγνώστη μια αίσθηση ολοκλήρωσης μετά την ολοκλήρωση κάθε υποενότητας. Η κατάτμηση συνιστάται από μεγάλες εταιρείες, όπως στον οδηγό στυλ γραφής της Microsoft <https://docs.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions# complex-procedures>`__, καθώς και από την έρευνα της Nielsen Norman Group σχετικά με τη διαίρεση σε τμήματα και τη χρηστικότητα <https://www.nngroup.com/articles/short-term-memory-and-web-usability/>`__.

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

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

• Στοχεύστε σε όχι περισσότερα από τέσσερα υποβήματα σε κάθε κύριο βήμα.

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

• Πάρα πολλά υπο-βήματα μπορεί να υποδηλώνουν ότι πρέπει να χωρίσετε μερικά από αυτά τα βήματα σε μια νέα ενότητα βημάτων.

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

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

  • Προαιρετικό: Εισαγάγετε μια περιγραφή για το αποθετήριο σας.

• Χρησιμοποιήστε την υπό όρους πρόταση Αν (συνθήκη) τότε (αποτέλεσμα) για να προσδιορίσετε τα βήματα που ισχύουν μόνο εάν πληρούνται ορισμένα κριτήρια. Ξεκινήστε πάντα τα υπό προϋποθέσεις βήματα με μια συνθήκη, έτσι ώστε οι χρήστες που δεν πληρούν τη συνθήκη να μπορούν να παραλείψουν το βήμα. Για παράδειγμα,

  • Εάν είστε χρήστης των Windows, εγκαταστήστε το λογισμικό VM VirtualBox στον υπολογιστή σας.

Για περισσότερες πληροφορίες σχετικά με τις διαδικασίες συγγραφής, ανατρέξτε στον οδηγό στυλ τεκμηρίωσης προγραμματιστών της Google. <https://developers.google.com/style/procedures>__

Δομή σελίδας

• Δημιουργήστε ένα περίγραμμα των επικεφαλίδων που θέλετε να συμπεριλάβετε στο έγγραφο πριν αρχίσετε να γράφετε.

  • Χρησιμοποιήστε το περίγραμμα για να συγκεντρώσετε τις σκέψεις σας σχετικά με τα κύρια θέματα που πρέπει να μεταφέρετε στους αναγνώστες σας.

  • Είναι πολύ πιο εύκολο να μετακινείς στοιχεία με επικεφαλίδες παρά να μετακινείς μπλοκ περιεχομένου.

• Μπορεί επίσης να διαπιστώσετε ότι πρέπει να δημιουργήσετε δύο άρθρα, εάν το θέμα αρχίσει να διευρύνεται.

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

Τίτλοι και ονόματα αρχείων

• Δημιουργήστε έναν τίτλο που να περιγράφει το περιεχόμενο του άρθρου.

• Κάντε τον τίτλο μοναδικό στο χώρο της εφαρμογής σας.

• Κάντε τον τίτλο και το όνομα του αρχείου να είναι τα ίδια: είναι δύσκολο να αναγνωρίσετε το όνομα του αρχείου όταν ο τίτλος και το όνομα του αρχείου διαφέρουν.

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

Ακολουθούν μερικά παραδείγματα τίτλων και οι προτεινόμενες δομές των ονομάτων των αρχείων:

• Χρήση μίας τοστιέρας

  • using-a-toaster.rst

• Φρυγανίστε μια φέτα ψωμί

  • toast-slice-of-bread.rst

Ορισμοί

Εάν χρησιμοποιείτε επανειλημμένα όρους σε ένα μεγάλο άρθρο, μπορείτε να τους ορίσετε μία φορά και στη συνέχεια να τους χρησιμοποιείτε κατ” επανάληψη στο σώμα του άρθρου.

---

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