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

Follow these writing guidelines when developing content using The Good Docs Project templates.

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

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

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

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

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

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

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

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

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

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

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

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

• For procedures with numerous steps, consider “chunking” content into sub-sections of 5-10 steps. It makes the information easier to read and remember, and gives the reader a sense of accomplishment after each chunk is completed. Chunking is recommended by major companies, such as in Microsoft’s writing style guide, and from the Nielsen Norman Group’s research on chunking and usability.

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

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

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

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

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

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

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

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

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

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

For more information on writing procedures, see the Google developer documentation style guide.

Δομή σελίδας

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

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

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

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

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

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

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

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

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

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

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

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

  • using-a-toaster.rst

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

  • toast-slice-of-bread.rst

Ορισμοί

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

---

Explore other guides and templates from The Good Docs Project.