Τεχνική γραφή για προγραμματιστές

HTML, CSS, JavaScript, Python, PHP, C++, Dart — υπάρχουν τόσες πολλές γλώσσες προγραμματισμού εκεί έξω και μπορεί ακόμη και να μιλάτε απόλυτα σε αρκετές από αυτές! Αλλά καθώς στοχεύουμε να γράφουμε περισσότερο και καλύτερο κώδικα, ο τρόπος που γράφουμε και επικοινωνούμε στην καθημερινή γλώσσα γίνεται όλο και πιο σημαντικός… και ίσως ακόμη και να παραβλέπεται.

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

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

Περιμένετε, τεχνική γραφή; Ναι, αυτό ακριβώς εννοώ. Πιστεύω πραγματικά ότι είμαστε όλοι συγγραφείς με τη μια ή την άλλη έννοια. Και είμαι εδώ για να σας δώσω ένα primer με συμβουλές γραφής, συμβουλές και παραδείγματα για το πώς μπορεί να σας κάνει καλύτερο προγραμματιστή και επικοινωνιακό.

Η τεχνική γραφή είναι παντού

Πέρυσι, η ομάδα πίσω από τον δημοφιλή πελάτη Mac Git, Tower, ρωτήθηκαν πάνω από 4,000 προγραμματιστές και διαπίστωσε ότι σχεδόν το 50% από αυτούς περνούσαν μεταξύ 3-6 ώρες την ημέρα γράφοντας κώδικα.

Και ναι, αυτή είναι μια έρευνα που ρωτά μια πολύ εξειδικευμένη ομάδα, αλλά φαντάζομαι ότι πολλοί από εμάς πέφτουμε κάπου σε αυτό το εύρος. Όποια και αν είναι η περίπτωση, ένας προγραμματιστής δεν γράφει κώδικα 24/7, γιατί όπως δείχνει αυτή η δημοσκόπηση, ξοδεύουμε πολύ χρόνο κάνοντας άλλα πράγματα.

Αυτό μπορεί να περιλαμβάνει:

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

Φυσικά, υπάρχει πάντα χρόνος για διαλείμματα μπάνιου και για το Wordle επίσης.

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

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

Αυτό είναι το Technical Writing 101.

Και δεν τελειώνει καν εδώ. Σε ορισμένους προγραμματιστές αρέσει επίσης να φτιάχνουν τα δικά τους προϊόντα, πράγμα που σημαίνει ότι πρέπει να κάνουν το μάρκετινγκ μέρος της δουλειάς τους. Η τεχνική γραφή παίζει τεράστιο ρόλο και σε αυτό. Λοιπόν ναι. Νομίζω ότι είναι πολύ δίκαιο να πούμε ότι η τεχνική γραφή είναι πράγματι παντού.

Τι είναι η καλή γραμματική;

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

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

Επιτρέψτε μου να σας δώσω μια γρήγορη περιγραφή της γλώσσας.

Η αγγλική σύνταξη

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

Οι λέξεις είναι τα δομικά στοιχεία των αγγλικών και πέφτουν σε οκτώ κουβάδες:

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

Φωνή και τόνος

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

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

1. Μου αρέσει ο προγραμματισμός.
2. I Μου αρέσει προγραμματισμός! :)

Είναι εύκολο να συγχέετε τη φωνή με τον τόνο και το αντίστροφο.

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

Το ίδιο μήνυμα, γραμμένο με δύο διαφορετικές φωνές:

• Διασκέδαση: "Επεκτείνετε το κοινωνικό σας δίκτυο και μείνετε ενημερωμένοι για ό,τι τρέχει τώρα."
• Σοβαρός: «Βρείτε θέσεις εργασίας σε μία από τις μεγαλύτερες εφαρμογές κοινωνικής δικτύωσης και την αγορά εργασίας στο διαδίκτυο».

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

Εδώ είναι ένας άλλος τρόπος για να το σκεφτείτε: η φωνή σας δεν αλλάζει ποτέ, αλλά ο τόνος σας αλλάζει. Η φωνή σας μοιάζει με αυτό που είστε ως άτομο, ενώ ο τόνος είναι ο τρόπος που αντιδράτε σε μια δεδομένη κατάσταση.

Ενεργητική και παθητική φωνή

Μια πρόταση περιέχει πάντα έναν ηθοποιό, ένα ρήμα και έναν στόχο. Η σειρά με την οποία έρχονται αυτά καθορίζει αν η πρόταση είναι γραμμένη με ενεργητική ή παθητική φωνή.

Ο ηθοποιός έρχεται πρώτος σε ένα ενεργητική φωνή. Για παράδειγμα: "Το CSS ζωγραφίζει το φόντο."

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

Με ένα παθητική φωνή, ο ηθοποιός έρχεται τελευταίος. (Βλέπετε τι έκανα εκεί;) Αυτό σημαίνει ότι ο ηθοποιός μας - CSS σε αυτήν την περίπτωση - έρχεται στο τέλος ως εξής: "Το φόντο είναι ζωγραφισμένο από CSS."

Οι αναγνώστες συνήθως μετατρέπουν μια παθητική φωνή σε μια ενεργητική φωνή στο κεφάλι τους, με αποτέλεσμα περισσότερο χρόνο επεξεργασίας. Αν έχετε ακούσει ποτέ ότι το γράψιμο με ενεργή φωνή είναι καλύτερο, αυτός είναι συνήθως ο λόγος. Οι συγγραφείς τεχνολογίας προτιμούν την ενεργή φωνή τις περισσότερες φορές, με ελάχιστες εξαιρέσεις, όπως η αναφορά σε έρευνα: «Έχει προταθεί ότι…»

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

Αποφυγή λαθών

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

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

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

Γράψιμο σχολίων κώδικα

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

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

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

Αντίθετα, χρησιμοποιήστε σχόλια που παρέχουν περισσότερες πληροφορίες:

red *= 1.2 // Apply a 'reddish' effect to the image

Είναι όλα σχετικά με το πλαίσιο. «Τι είδους πρόγραμμα χτίζω;» είναι ακριβώς το είδος της ερώτησης που θα έπρεπε να κάνετε στον εαυτό σας.

Τα σχόλια πρέπει να προσθέτουν αξία

Πριν εξετάσουμε τι κάνει ένα "καλό" σχόλιο κώδικα, εδώ είναι δύο παραδείγματα νωχελικών σχολίων:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

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

Τα σχόλια πρέπει να αντικατοπτρίζουν τον τρέχοντα κωδικό

Τα παρωχημένα σχόλια δεν είναι σπάνια θέα σε μεγάλα έργα. τολμώ να πω μέσα πλέον έργα.

Ας φανταστούμε τον Ντέιβιντ, έναν προγραμματιστή και έναν πολύ καλό τύπο για παρέα. Ο David θέλει να ταξινομήσει μια λίστα συμβολοσειρών αλφαβητικά από το Α έως το Ω, επομένως κάνει το προφανές στο JavaScript:

cities = sortWords(cities) // sort cities from A to Z

Στη συνέχεια, ο David συνειδητοποιεί ότι η sortWords() ταξινομεί πραγματικά λίστες από το Ω στο Α. Αυτό δεν είναι πρόβλημα, καθώς μπορεί απλώς να αντιστρέψει την έξοδο:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

Δυστυχώς, ο David δεν ενημέρωσε το σχόλιό του στον κώδικα.

Τώρα φανταστείτε ότι δεν σας είπα αυτή την ιστορία, και το μόνο που είδατε ήταν ο παραπάνω κωδικός. Φυσικά θα σκεφτόσασταν ότι μετά την εκτέλεση αυτής της δεύτερης γραμμής κώδικα, οι "πόλεις" θα ταξινομηθούν από το Ω στο Α! Όλο αυτό το φιάσκο σύγχυσης προκλήθηκε από ένα μπαγιάτικο σχόλιο.

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

Αυτός είναι ένας απλός κανόνας που θα σώσει εσάς και την ομάδα σας από πολλά τεχνικό χρέος.

Τώρα που ξέρουμε πώς μοιάζουν τα κακογραμμένα σχόλια, ας δούμε μερικά καλά παραδείγματα.

Τα σχόλια πρέπει να εξηγούν τον μονολεκτικό κώδικα

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

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

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

Τα σχόλια μπορούν να προσδιορίσουν μελλοντικές εργασίες

Ένα άλλο χρήσιμο πράγμα που πρέπει να κάνετε με τα σχόλια είναι να παραδεχτείτε ότι υπάρχει περισσότερη δουλειά να γίνει.

// TODO: use a more efficient algorithm
linearSort(ids)

Με αυτόν τον τρόπο, μπορείτε να παραμείνετε συγκεντρωμένοι στη ροή σας. Και σε μεταγενέστερη ημερομηνία, εσείς (ή κάποιος άλλος) μπορείτε να επιστρέψετε και να το διορθώσετε.

Τα σχόλια μπορούν να συνδεθούν πίσω στην πηγή

Έτσι, μόλις βρήκατε μια λύση στο πρόβλημά σας στο StackOverflow. Μετά την αντιγραφή-επικόλληση αυτού του κώδικα, μερικές φορές είναι καλό να διατηρείτε έναν σύνδεσμο προς την απάντηση που σας βοήθησε, ώστε να μπορείτε να επιστρέψετε σε αυτόν για μελλοντική αναφορά.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

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

Σύνταξη αιτημάτων έλξης

Τραβήξτε αιτήματα (PRιθ) αποτελούν θεμελιώδη πτυχή οποιουδήποτε έργου. Βρίσκονται στο επίκεντρο των κριτικών κώδικα. Και οι κριτικές κώδικα μπορούν γρήγορα να γίνουν εμπόδιο στην απόδοση της ομάδας σας χωρίς καλή διατύπωση.

Ενα καλό PR η περιγραφή συνοψίζει τι γίνεται αλλαγή και WHY φτιάχνεται. Τα μεγάλα έργα έχουν ένα πρότυπο αιτήματος έλξης, όπως αυτό προσαρμοσμένο από α πραγματικό παράδειγμα:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Αποφύγετε ασαφείς PR τίτλους

Αποφύγετε τους τίτλους που μοιάζουν με αυτό:

• Διορθώστε την κατασκευή.
• Διορθώστε το σφάλμα.
• Προσθήκη έμπλαστρου.

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

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

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

• Υποστήριξη προσαρμοσμένων ιδιοτήτων srcset στο NgOptimizedImage
• Προεπιλεγμένη διαμόρφωση εικόνας σε ποιότητα εικόνας 75%.
• Προσθέστε ρητούς επιλογείς για όλα τα ενσωματωμένα ControlValueAccessors

Αποφύγετε το μακρύ PRs

Ενα μεγάλο PR σημαίνει μια τεράστια περιγραφή και κανείς δεν θέλει να ελέγξει εκατοντάδες ή χιλιάδες γραμμές κώδικα, μερικές φορές απλώς για να καταλήξει να απορρίψει το όλο θέμα!

Αντίθετα, θα μπορούσατε:

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

Δεν είναι πολύ πιο καθαρό τώρα;

Δώστε λεπτομέρειες στο PR σώμα

Σε αντίθεση με την PR τίτλος, το σώμα είναι ο μέρος για όλες τις λεπτομέρειες, συμπεριλαμβανομένων:

• Γιατί είναι το PR γίνεται;
• Γιατί είναι αυτή η καλύτερη προσέγγιση;
• Τυχόν ελλείψεις στην προσέγγιση και ιδέες για την επίλυσή τους εάν είναι δυνατόν
• Ο αριθμός σφάλματος ή εισιτηρίου, τα αποτελέσματα συγκριτικής αξιολόγησης κ.λπ.

Αναφορά σφαλμάτων

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

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

Για παράδειγμα, έρχονται τα περισσότερα μεγάλα έργα ένα πρότυπο:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Συλλέξτε στιγμιότυπα οθόνης

Καταγράψτε το πρόβλημα χρησιμοποιώντας το δικό σας βοηθητικό πρόγραμμα λήψης οθόνης του συστήματος.

Αν είναι στιγμιότυπο οθόνης του α CLI πρόγραμμα, βεβαιωθείτε ότι το κείμενο είναι σαφές. Αν είναι α UI πρόγραμμα, βεβαιωθείτε ότι το στιγμιότυπο οθόνης καταγράφει τα σωστά στοιχεία και καταστάσεις.

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

Πώς να αναπαράγετε το πρόβλημα

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

Εδώ είναι ένα παράδειγμα:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Προτείνετε μια αιτία

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

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

Επικοινωνία με πελάτες

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

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

Λοιπόν, πώς μπορούμε να μετριάζουμε αυτό το στερεότυπο; Ρωτήστε τους πελάτες τι θέλουν και ακούτε πάντα τα σχόλιά τους. Δείτε πώς να το κάνετε αυτό.

Κάντε τις σωστές ερωτήσεις

Ξεκινήστε βεβαιώνοντας ότι εσείς και ο πελάτης βρίσκεστε στην ίδια σελίδα:

• Ποιο είναι το κοινό-στόχος σας;
• Ποιος είναι ο στόχος του ιστότοπου;
• Ποιος είναι ο πλησιέστερος ανταγωνιστής σας και τι κάνουν σωστά;

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

• Είστε εντάξει με αυτό ακόμα κι αν συνοδεύεται από ένα επιπλέον κόστος απόδοσης;
• Η μετακίνηση του εξαρτήματος μας βοηθά να επιτύχουμε καλύτερα τον στόχο μας;
• Ωραία, ποιος είναι υπεύθυνος να το διατηρήσει μετά την εκτόξευση; 
• Γνωρίζετε από κοντά αν η αντίθεση μεταξύ αυτών των δύο χρωμάτων υπερβαίνει τα πρότυπα WCAG AA;

Οι ερωτήσεις είναι πολύ πιο αθώες και προωθούν την περιέργεια έναντι της εχθρότητας.

Πουλήστε τον εαυτό σας

Εάν κάνετε μια πρόταση σε έναν υποψήφιο πελάτη, θα πρέπει να τον πείσετε να σας προσλάβει. Γιατί να επιλέξει ο πελάτης εσάς; Είναι σημαντικό να προσδιορίσετε τα ακόλουθα:

• Ποιός είσαι
• Τι κάνεις
• Γιατί είσαι κατάλληλος για τη δουλειά
• Σύνδεσμοι προς σχετική εργασία που έχετε κάνει

Και μόλις πιάσετε τη δουλειά και χρειαστεί να συντάξετε ένα συμβόλαιο, να θυμάστε ότι δεν υπάρχει περιεχόμενο πιο εκφοβιστικό από μια δέσμη νομικών. Παρόλο που είναι γραμμένο για σχεδιαστικά έργα, το Συμβόλαιο Killer μπορεί να είναι μια ωραία αφετηρία για να γράψετε κάτι πολύ πιο φιλικό.

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

Μικροτυπία γραφής

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

Αυτός μπορεί να είναι ο λόγος που μερικές φορές βλέπουμε σφάλματα όπως αυτό:

Error: Unexpected input (Code 693)

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

Αποφύγετε την τεχνική ορολογία

Οι περισσότεροι άνθρωποι δεν γνωρίζουν τι είναι διακομιστής, ενώ το 100% των προγραμματιστών γνωρίζουν. Γι' αυτό δεν είναι ασυνήθιστο να βλέπετε ασυνήθιστους όρους γραμμένους σε ένα μήνυμα σφάλματος, π.χ API ή "timeout execution".

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

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

Ποτέ μην κατηγορείτε τον χρήστη

Φανταστείτε το εξής: Προσπαθώ να συνδεθώ στην πλατφόρμα σας. Ανοίγω λοιπόν το πρόγραμμα περιήγησής μου, επισκέπτομαι τον ιστότοπό σας και εισάγω τα στοιχεία μου. Τότε μου λένε: "Το email/ο κωδικός πρόσβασής σας είναι λάθος."

Παρόλο που φαίνεται δραματικό να σκέφτομαι ότι αυτό το μήνυμα είναι εχθρικό, υποσυνείδητα με κάνει να νιώθω ηλίθιος. Η Microcopy λέει ότι δεν είναι ποτέ εντάξει να κατηγορείς τον χρήστη. Δοκιμάστε να αλλάξετε το μήνυμά σας σε κάτι λιγότερο αιχμηρό, όπως αυτό το παράδειγμα προσαρμοσμένο από τη σύνδεση του Mailchimp: «Συγγνώμη, αυτός ο συνδυασμός email-κωδικού πρόσβασης δεν είναι σωστός. Μπορούμε να σας βοηθήσουμε να ανακτήσετε τον λογαριασμό σας."

Θα ήθελα επίσης να προσθέσω τη σημασία της αποφυγής ΟΛΑ τα ΚΕΦΑΛΑΙΑ και τα θαυμαστικά! Σίγουρα, μπορούν να χρησιμοποιηθούν για να μεταδώσουν ενθουσιασμό, αλλά σε μικροαντίγραφο δημιουργούν μια αίσθηση εχθρότητας προς τον χρήστη.

Μην κατακλύζετε τον χρήστη

Η χρήση του χιούμορ στη μικροτυπία σας είναι καλή ιδέα! Μπορεί να ελαφρύνει τη διάθεση και είναι ένας εύκολος τρόπος να περιορίσετε την αρνητικότητα που προκαλείται ακόμα και από τα χειρότερα λάθη.

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

Το Mailchimp τα λέει καλά:

[Δ]Μην παίρνετε τα δυνατά σας για να κάνετε ένα αστείο — το αναγκαστικό χιούμορ μπορεί να είναι χειρότερο από το καθόλου. Εάν δεν είστε σίγουροι, κρατήστε ένα ίσιο πρόσωπο.

(Η υπογράμμιση δική μου)

Σύνταξη προσβάσιμης σήμανσης

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

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

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

Πράγματα όπως:

Ο Andy Bell προσφέρει κάποια σχετικά μικρά πράγματα που μπορείτε να κάνετε για να κάνετε το περιεχόμενο πιο προσιτό, και αξίζει τον κόπο να τα ελέγξετε. Και μόνο για κλωτσιές, Ο John Rhea δείχνει μερικά προσεγμένα κόλπα επεξεργασίας που είναι δυνατά όταν εργαζόμαστε με σημασιολογικά στοιχεία HTML.

Συμπέρασμα

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

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

Τεχνικοί πόροι γραφής

Αν σας ενδιαφέρει η τεχνική γραφή:

Αν σας ενδιαφέρει το copywriting:

Εάν ενδιαφέρεστε για μικροαντίγραφο:

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

Εάν ενδιαφέρεστε να γράψετε για προσβασιμότητα: