Scrittura tecnica per sviluppatori PlatoBlockchain Data Intelligence. Ricerca verticale. Ai.

Scrittura tecnica per sviluppatori

HTML, CSS, JavaScript, Python, PHP, C++, Dart: ci sono così tanti linguaggi di programmazione in circolazione e potresti persino parlarne perfettamente molti! Ma poiché miriamo a scrivere codice sempre maggiore e migliore, il modo in cui scriviamo e comunichiamo nel linguaggio quotidiano diventa sempre più importante... e forse anche trascurato.

Il modo in cui scriviamo sul codice è probabilmente altrettanto importante quanto il codice stesso. E nonostante dove ti trovi su quella linea, siamo tutti d'accordo sul fatto che le nostre parole hanno il potenziale sia per aiutare che per danneggiare l'efficacia del codice.

In questo articolo, voglio delineare come questi due campi apparentemente distinti, programmazione e scrittura, possano unirsi e portare le nostre capacità di sviluppatore a un livello superiore.

Aspetta, scrittura tecnica? Sì, è esattamente quello che intendo. Credo davvero che siamo tutti scrittori in un senso o nell'altro. E sono qui per darti un'introduzione con suggerimenti di scrittura, consigli ed esempi su come può renderti uno sviluppatore e un comunicatore migliore.

Sommario

La scrittura tecnica è ovunque

L'anno scorso, il team dietro il popolare client Mac Git, Tower, hanno intervistato più di 4,000 sviluppatori e ha scoperto che quasi il 50% di loro trascorreva dalle 3 alle 6 ore al giorno scrivendo codice.

Scrittura tecnica per sviluppatori

E sì, questo è un sondaggio che coinvolge un gruppo piuttosto di nicchia, ma immagino che molti di noi ricadano da qualche parte in quell'intervallo. In ogni caso, uno sviluppatore non scrive codice 24 ore su 7, XNUMX giorni su XNUMX, perché come suggerisce questo sondaggio, passiamo molto tempo a fare altre cose.

Ciò potrebbe includere:

  • demo di una nuova funzionalità,
  • documentando quella nuova funzionalità,
  • aggiornare un ticket di lavoro relativo a quella nuova funzionalità, o
  • lavoro di backlog per supportare quella nuova funzionalità.

Naturalmente c'è sempre tempo per le pause bagno e anche per Wordle.

Ad ogni modo, la maggior parte delle cose che facciamo tipicamente implicano la comunicazione con persone come il tuo team, colleghi, clienti, utenti e altri sviluppatori.

Quindi trascorriamo buona parte del nostro tempo comunicando con gli esseri umani parole oltre alla comunicazione che abbiamo con i computer attraverso codice. Le parole sono linguaggio scritto. E se scrivessimo meglio le nostre parole, comunicheremmo meglio. Quando comunichiamo meglio, è più probabile che otteniamo ciò che vogliamo.

Questa è la scrittura tecnica 101.

Diagramma di Venn che mostra la sovrapposizione tra scrittura tecnica e codifica.
Scrittura tecnica per sviluppatori

E non finisce qui... Ad alcuni programmatori piace anche realizzare i propri prodotti, il che significa che devono rendere il marketing parte del loro lavoro. Anche la scrittura tecnica gioca un ruolo enorme in questo. Quindi sì. Penso che sia abbastanza giusto dire che la scrittura tecnica lo è infatti ovunque.

Cos'è una buona grammatica?

Con così tanti linguaggi di programmazione in circolazione, l’ultima cosa che vogliamo è impararne un altro.

Grammatica è parte integrante dell'inglese e libera tutto il potenziale della comunicazione. Ci rende più formali, professionali e coerenti.

Lascia che ti dia una breve panoramica sulla lingua.

La sintassi inglese

Proprio come i linguaggi di programmazione, l’inglese ha una sintassi ben definita e inizia con le parole.

Le parole sono gli elementi costitutivi dell'inglese e si dividono in otto categorie:

Frase codificata a colori che mostra la sintassi inglese.
Scrittura tecnica per sviluppatori
Nomi

Questi possono essere nomi di persone, animali, luoghi, concetti e oggetti.

Esempio:
CSS è uno dei linguaggi principali dello sviluppo front-end.

Verbi

I verbi trasmettono l'azione. Anche “è” può essere considerato un’azione.

Esempio:
Marcia codici al mattino e risposte e-mail nel pomeriggio.

Aggettivi

Gli aggettivi sono il modo in cui descriviamo i nomi. Sono come meta che aggiungono più dettagli a una frase per dipingere un'immagine vivida.

Consigli d'uso:

  • CSS è un eleganti ed poetico Lingua.
  • L'HTML per le tabelle è complesso ed ingombrante.
  • Il modello della scatola è importante per comprendere i CSS.
Preposizioni

Le preposizioni creano una relazione tra un sostantivo e altre parole, spesso indicando direzione, tempo, luogo e spazio.

Consigli d'uso:

  • Hai impegnato il tuo lavoro a il recupero?
  • Qual è l'approccio migliore per questo componente?
  • Abbiamo condotto interviste con utenti reali.
Avverbi

A volte le azioni devono essere più specifiche, quindi usiamo avverbi come “corre”. veloce" e "compila lentamente.” Spesso finiscono in “-ly”.

Consigli d'uso:

  • Questo è anche facilmente l'idea migliore di tutte.
  • Chip attese pazientemente per il feedback di Dale.
  • La squadra ha lavorato diligentemente sul progetto.
Congiunzioni

Le congiunzioni collegano le frasi in una frase. Ricorda questa canzone classica dallo spettacolo Rocce della scuola?

Consigli d'uso:

  • CSS per lo stile while HTML è per il markup.
  • Sì, scrivo codice, ma Mi occupo anche di design.
  • Questo risolve il bug. ancora ne ha introdotto uno nuovo.
transizioni

I paragrafi sono costituiti da frasi collegate tra loro tramite transizioni.

Consigli d'uso:

  • Esistono molti linguaggi di programmazione. Tuttavia, solo pochi vengono utilizzati nel settore web.
  • Nome, clona la directory.
  • Mi piace questo approccio ma d'altra parte, ne conosco un altro.
Pronomi

Quando i nomi diventano ripetitivi, li sostituiamo con pronomi come: “lui”, “esso” e “quello”.

Consigli d'uso:

  • I CSS sono un linguaggio per fogli di stile. Noi usiamo it per dare stile ai siti web.
  • Tony ama programmare e he pratica ogni giorno.
  • I nostri clienti sono esperti di tecnologia perché di conoscere il codice.

Pensa a questi come UI componenti: sono pezzi modulari che puoi spostare per costruire una frase completa e robusta, nello stesso modo in cui potresti mettere insieme una frase completa e robusta UI. Tutti i componenti devono essere sempre presenti? Certamente no! Assembla una frase con i pezzi che ti servono per completare l'esperienza, proprio come faresti con un'interfaccia.

Voce e tono

Vocabolario, punteggiatura, struttura della frase e scelta delle parole. Questi sono tutti gli ingredienti dell'inglese. Li usiamo per condividere idee, comunicare con i nostri amici e familiari e inviare e-mail ai nostri colleghi.

Ma è fondamentale considerare il suono dei nostri messaggi. È sorprendente come un punto esclamativo possa cambiare completamente il tono di un messaggio:

  1. Mi piace programmare.
  2. I piace programmazione! :)

È facile confondere la voce con il tono e viceversa.

Voce è ciò che riguarda la nostra scelta delle parole, che dipende dal contesto. Ad esempio, è più probabile che un tutorial per principianti utilizzi lo slang e un linguaggio informale per trasmettere una voce amichevole, mentre la documentazione potrebbe essere scritta in modo formale, serio e professionale nel tentativo di arrivare direttamente al punto.

Lo stesso messaggio, scritto con due voci diverse:

  • Fun: "Espandi il tuo social network e rimani aggiornato su ciò che è di tendenza adesso."
  • Grave: "Trova lavoro su una delle più grandi app di social network e sul mercato del lavoro online."

Non è insolito scrivere accidentalmente messaggi che appaiono condiscendenti, offensivi e poco professionali. Qui è dove tono entra in gioco. Leggi i tuoi messaggi ad alta voce, chiedi ad altre persone di leggerli per te e sperimenta la punteggiatura e la struttura delle frasi. È così che affini il tuo tono.

Ecco un altro modo di pensarla: la tua voce non cambia mai, ma il tuo tono sì. La tua voce è simile a chi sei come persona, mentre il tono è il modo in cui rispondi in una determinata situazione.

Voce attiva e passiva

Una frase contiene sempre un attore, un verbo e un bersaglio. L'ordine in cui si presentano determina se la frase è scritta con voce attiva o passiva.

L'attore viene per primo in un voce attiva. Ad esempio: “I CSS dipingono lo sfondo”.

Le frasi che utilizzano una voce attiva sono più semplici delle loro controparti. Sono più chiari, più brevi e più comprensibili: perfetti per una voce più professionale che arriva dritta al punto.

Con un voce passiva, l'attore arriva per ultimo. (Vedi cosa ho fatto lì?) Ciò significa che il nostro attore - CSS in questo caso - arriva alla fine in questo modo: "Lo sfondo è dipinto da CSS".

I lettori di solito convertono una voce passiva in una voce attiva nella loro testa, con conseguente maggiore tempo di elaborazione. Se hai mai sentito dire che scrivere con voce attiva è meglio, di solito è questo il motivo. Gli scrittori di tecnologia preferiscono la voce attiva per la maggior parte del tempo, con pochissime eccezioni come la citazione di ricerche: "È stato suggerito che..."

Ma ciò non significa che dovresti sempre cercare di avere una voce attiva. Passare dall'uno all'altro, anche nello stesso paragrafo, può far sì che i tuoi contenuti fluiscano più fluidamente da una frase all'altra, se utilizzati in modo efficace.

Evitare errori

La grammatica riguarda la struttura e la correttezza del linguaggio e non c'è niente di meglio per raggiungere questo obiettivo che una rapida correzione di bozze del tuo documento. È molto importante liberare i tuoi scritti da errori di ortografia, problemi grammaticali e imperfezioni semantiche.

Alla fine di questo articolo ti mostrerò i preziosi strumenti che i professionisti utilizzano per evitare errori di scrittura. Ovviamente, al giorno d'oggi ci sono correttori ortografici incorporati in quasi tutto; i nostri editor di codice dispongono anche di plug-in per il controllo ortografico e l'intreccio per aiutare a prevenire errori. 

Ma se stai cercando uno strumento completo per tutto ciò che riguarda la grammatica, Grammarly è uno degli strumenti più utilizzati. Non riceverò alcuna ricompensa per questo o altro. È semplicemente uno strumento davvero eccezionale che molti editor e scrittori utilizzano per scrivere contenuti puliti e chiari, in modo simile a come potresti utilizzare Emmet, eslint o qualsiasi altro linter per scrivere codice pulito e chiaro.

Scrittura di commenti sul codice

Ciò che scriviamo per altri sviluppatori può avere un grande impatto sulla qualità complessiva del nostro lavoro, sia che si tratti di ciò che scriviamo nel codice, di come lo spieghiamo o di come diamo feedback su una parte di codice.

È interessante notare che ogni linguaggio di programmazione è dotato di un set standard di funzionalità per scrivere un commento. Dovrebbero spiegare cosa sta facendo il codice. Con questo non intendo commenti vaghi come questo:

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

Utilizza invece commenti che forniscono ulteriori informazioni:

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

È tutta una questione di contesto. "Che tipo di programma sto costruendo?" è esattamente il tipo di domanda che dovresti farti.

I commenti dovrebbero aggiungere valore

Prima di esaminare ciò che rende un commento di codice “buono”, ecco due esempi di commenti pigri:

const age = 32 // Initialize `age` to 32
filter: blur(32px); /* Create a blur effect with a 32px radius */

Ricorda che lo scopo di un commento è aggiungere valore a un pezzo di codice, non ripeterlo. Se non puoi farlo, è meglio lasciare il codice così com'è. Ciò che rende questi esempi “pigri” è che si limitano a ribadire ciò che il codice sta ovviamente facendo. In questo caso, i commenti sono ridondanti perché ci dicono quello che già sappiamo: non aggiungono valore!

I commenti dovrebbero riflettere il codice attuale

I commenti obsoleti non sono rari nei grandi progetti; oserei dire dentro maggior parte

Immaginiamo David, un programmatore e un ragazzo simpatico a tutto tondo con cui uscire. David vuole ordinare un elenco di stringhe in ordine alfabetico dalla A alla Z, quindi fa l'ovvio in JavaScript:

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

David poi si rende conto che sortWords() in realtà ordina gli elenchi dalla Z alla A. Questo non è un problema, poiché può semplicemente invertire l'output:

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

Sfortunatamente, David non ha aggiornato il suo commento sul codice.

Ora immagina che io non ti abbia raccontato questa storia e che tutto ciò che hai visto sia stato il codice sopra. Penseresti naturalmente che dopo aver eseguito la seconda riga di codice, le "città" verrebbero ordinate dalla Z alla A! Tutto questo fiasco di confusione è stato causato da un commento stantio.

Anche se questo potrebbe essere un esempio esagerato, qualcosa di simile può accadere (e spesso accade) se si corre contro una scadenza ravvicinata. Per fortuna, questo può essere evitato seguendo una semplice regola… cambia i tuoi commenti nello stesso momento in cui cambi il codice.

Questa è una semplice regola che salverà te e il tuo team da molti problemi debito tecnico.

Ora che sappiamo come sono i commenti scritti male, diamo un'occhiata ad alcuni buoni esempi.

I commenti dovrebbero spiegare il codice unidiomatico

A volte, il naturale il modo di fare le cose non è giusto. I programmatori potrebbero dover "infrangere" un po' gli standard, ma quando lo fanno, è consigliabile lasciare un piccolo commento che spieghi le loro motivazioni:

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

È utile, vero? Se fossi responsabile della revisione di questo codice, potresti essere stato tentato di correggerlo senza che quel commento spiegasse cosa succede.

I commenti possono identificare attività future

Un'altra cosa utile da fare con i commenti è ammettere che c'è ancora molto lavoro da fare.

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

In questo modo, puoi rimanere concentrato sul tuo flusso. E in un secondo momento, tu (o qualcun altro) potrete tornare e risolverlo.

Quindi, hai appena trovato una soluzione al tuo problema su StackOverflow. Dopo aver copiato e incollato il codice, a volte è una buona cosa mantenere un collegamento alla risposta che ti ha aiutato in modo da poter tornare ad esso per riferimento futuro.

Screenshot della copia di un collegamento su StackOverflow.
Scrittura tecnica per sviluppatori
// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

Questo è importante perché le soluzioni possono cambiare. È sempre utile sapere da dove proviene il tuo codice nel caso in cui si rompa.

Scrittura di richieste pull

Richieste pull (PRs) sono un aspetto fondamentale di qualsiasi progetto. Sono al centro delle revisioni del codice. E le revisioni del codice possono rapidamente diventare un collo di bottiglia nelle prestazioni del tuo team senza una buona formulazione.

Un buon PR la descrizione riassume che cosa è in corso un cambiamento e perché è stato realizzato. I progetti di grandi dimensioni hanno un modello di richiesta pull, come questo adattato da a esempio reale:

## 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…

Evita il vago PR titoli

Si prega di evitare titoli simili a questi:

  • Correggi la creazione.
  • Bug fix.
  • Aggiungi la toppa.

Neanche questi tentativo per descrivere con quale build, bug o patch abbiamo a che fare. Un piccolo dettaglio in più su quale parte della build è stata corretta, quale bug è stato risolto o quale patch è stata aggiunta può contribuire notevolmente a stabilire una migliore comunicazione e collaborazione con i tuoi colleghi. Stabilisce il livello e porta le persone sulla stessa pagina.

PR i titoli sono tradizionalmente scritti tempo imperativo. Sono un riepilogo di una riga dell'intero PRe dovrebbero descrivere che cosa viene fatto da PR.

Ecco alcuni buoni esempi:

  • Supporta attributi srcset personalizzati in NgOptimizedImage
  • Configurazione immagine predefinita con qualità immagine al 75%.
  • Aggiungi selettori espliciti per tutti i ControlValueAccessor incorporati

Evitare a lungo PRs

Un grande PR significa una descrizione enorme e nessuno vuole rivedere centinaia o migliaia di righe di codice, a volte solo per finire per respingere il tutto!

Invece potresti:

  • comunicare con il tuo team attraverso Problema,
  • fare un piano,
  • scomporre il problema in parti più piccole, o
  • lavorare ogni pezzo separatamente con il proprio PR.

Non è molto più pulito adesso?

Fornire i dettagli in PR stile di vita

Diversamente dal PR titolo, il corpo è , il posto per tutti i dettagli, tra cui:

  • Perché è il PR essendo fatto?
  • Perché questo è l'approccio migliore?
  • Eventuali carenze dell'approccio e idee per risolverle, se possibile
  • Il numero del bug o del ticket, i risultati del benchmark, ecc.

Segnalazione di bug

Le segnalazioni di bug sono uno degli aspetti più importanti di qualsiasi progetto. E tutti i grandi progetti si basano sul feedback degli utenti. Di solito, anche dopo innumerevoli test, sono gli utenti a trovare la maggior parte dei bug. Gli utenti sono anche grandi idealisti e talvolta hanno idee sulle funzionalità; per favore ascoltateli!

Per i progetti tecnici, tutto questo viene fatto segnalando i problemi. Un problema ben scritto è facile da trovare e a cui un altro sviluppatore può rispondere.

Ad esempio, la maggior parte dei grandi progetti arrivano Un modello:

 <!-- 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.

Raccogli screenshot

Cattura il problema utilizzando il tuo l'utilità di ripresa dello schermo del sistema.

Se è uno screenshot di a CLI programma, assicurarsi che il testo sia chiaro. Se è un UI programma, assicurati che lo screenshot catturi gli elementi e gli stati corretti.

Potrebbe essere necessario catturare un'interazione reale per dimostrare il problema. Se è così, prova a farlo registra GIF utilizzando uno strumento di registrazione dello schermo.

Come riprodurre il problema

È molto più semplice per i programmatori risolvere un bug quando è presente sul proprio computer. Ecco perché un buon commit dovrebbe includere i passaggi per riprodurre con precisione il problema.

Ecco un esempio:

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.

Suggerisci una causa

Sei tu quello che ha rilevato il bug, quindi forse puoi suggerire alcune potenziali cause per cui è lì. Forse il bug si verifica solo dopo aver riscontrato un determinato evento o forse si verifica solo su dispositivi mobili.

Inoltre, non può far male esplorare la base di codice e magari identificare la causa del problema. Quindi, il tuo problema verrà chiuso molto più rapidamente e probabilmente verrai assegnato a quello correlato PR.

Comunicare con i clienti

Potresti lavorare come libero professionista o forse sei lo sviluppatore principale di un piccolo team. In entrambi i casi, supponiamo che tu sia responsabile dell'interfaccia con i clienti su un progetto. 

Ora, lo stereotipo dei programmatori è che siamo poveri comunicatori. Siamo conosciuti per usare un gergo eccessivamente tecnico, dire agli altri cosa è possibile e cosa non è possibile e persino metterci sulla difensiva quando qualcuno mette in dubbio il nostro approccio.

Quindi, come possiamo mitigare questo stereotipo? Chiedi ai clienti cosa vogliono e ascolta sempre il loro feedback. Ecco come farlo.

Poni le domande giuste

Inizia assicurandoti che tu e il cliente siate sulla stessa pagina:

  • chi è il tuo pubblico di riferimento?
  • Qual è l'obiettivo del sito?
  • Chi è il tuo concorrente più vicino e cosa sta facendo bene?

Fare domande è anche un buon modo per scrivere in modo positivo, in particolare nelle situazioni in cui non sei d'accordo con il feedback o la decisione di un cliente. Fare domande costringe quella persona a sostenere le proprie affermazioni invece di attaccarla difendendo la propria posizione:

  • Sei d'accordo anche se comporta un costo aggiuntivo in termini di prestazioni?
  • Lo spostamento del componente ci aiuta a raggiungere meglio il nostro obiettivo?
  • Ottimo, chi è responsabile della manutenzione dopo il lancio? 
  • Sai se il contrasto tra questi due colori supera gli standard WCAG AA?

Le domande sono molto più innocenti e promuovono la curiosità piuttosto che l’animosità.

Vendi te stesso

Se stai facendo una proposta a un potenziale cliente, dovrai convincerlo ad assumerti. Perché il cliente dovrebbe scegliere te? E' importante specificare quanto segue:

  • Chi sei
  • Ciò che fai
  • Perché sei adatto per il lavoro
  • Collegamenti a lavori pertinenti che hai svolto

E una volta ottenuto il lavoro e hai bisogno di redigere un contratto, ricorda che non c'è contenuto più intimidatorio di un mucchio di termini legali. Anche se è scritto per progetti di design, the Contract Killer può essere un buon punto di partenza per scrivere qualcosa di molto più amichevole.

La tua attenzione ai dettagli potrebbe fare la differenza tra te e un altro sviluppatore che cerca di vincere lo stesso progetto. Nella mia esperienza, i clienti assumeranno più facilmente uno sviluppatore con cui pensano che gli piacerà lavorare piuttosto che quello che è tecnicamente il più competente o esperto per il lavoro.

Microcopia di scrittura

Microcopia è l'arte di scrivere in modo user-friendly UI messaggi, ad esempio errori. Scommetto che ci sono stati momenti in cui tu, come sviluppatore, hai dovuto scrivere messaggi di errore perché erano stati messi in secondo piano fino al momento del lancio.

Questo potrebbe essere il motivo per cui a volte vediamo errori come questo:

Error: Unexpected input (Code 693)

Gli errori sono l'ultima cosa che vuoi che i tuoi utenti debbano affrontare. Ma accadono e non possiamo farci niente. Ecco alcuni suggerimenti per migliorare le tue abilità di microcopia.

Evita il gergo tecnico

La maggior parte delle persone non sa cosa sia un server, mentre il 100% dei programmatori lo sa. Ecco perché non è insolito vedere termini insoliti scritti in un messaggio di errore, come API o "esecuzione del timeout".

A meno che tu non abbia a che fare con un cliente tecnico o una base di utenti, è probabile che la maggior parte dei tuoi utenti non abbia seguito un corso di informatica e non sappia come funziona Internet e perché una cosa particolare non funziona. Da qui l'errore.

Pertanto, un buon messaggio di errore non dovrebbe spiegare perché qualcosa è andato storto, perché tali spiegazioni potrebbero richiedere l'uso di termini tecnici spaventosi. Ecco perché è molto importante evitare di usare termini tecnici.

Non incolpare mai l'utente

Immagina questo: sto cercando di accedere alla tua piattaforma. Quindi apro il browser, visito il tuo sito web e inserisco i miei dati. Poi mi viene detto: "La tua email/password non è corretta".

Anche se sembra drammatico pensare che questo messaggio sia ostile, inconsciamente mi fa sentire stupido. Microcopy dice che non è mai giusto incolpare l'utente. Prova a cambiare il tuo messaggio in qualcosa di meno complicato, come questo esempio adattato dal login di Mailchimp: “Siamo spiacenti, la combinazione email-password non è corretta. Possiamo aiutarti a recuperare il tuo account."

Vorrei anche aggiungere l'importanza di evitare TUTTO MAIUSCOLO e punti esclamativi! Certo, possono essere usati per trasmettere eccitazione, ma al microscopio creano un senso di ostilità nei confronti dell'utente.

Non sopraffare l'utente

Usare l'umorismo nel tuo microcopy è una buona idea! Può alleggerire l'umore ed è un modo semplice per frenare la negatività causata anche dagli errori peggiori.

Ma se non lo usi perfettamente, può sembrare condiscendente e offensivo per l'utente. Questo è solo un big rischio da correre.

Mailchimp lo dice bene:

[Non] fare di tutto per fare una battuta: l'umorismo forzato può essere peggio di niente. Se non sei sicuro, mantieni un'espressione seria.

(enfasi mia)

Scrittura di markup accessibile

Potremmo facilmente dedicare un intero articolo all’accessibilità e al suo rapporto con la scrittura tecnica. Diamine, l'accessibilità è spesso inclusa nelle guide sullo stile dei contenuti, comprese quelle per Microsoft ed Mailchimp.

Sei uno sviluppatore e probabilmente sai già molto sull'accessibilità. Potresti anche essere uno degli sviluppatori più diligenti che rendono l'accessibilità una parte fondamentale del tuo flusso di lavoro. Tuttavia, è incredibile quanto spesso le considerazioni sull'accessibilità vengano messe in secondo piano, non importa quanto sia importante, come tutti sappiamo, rendere accessibili esperienze online che includano tutte le abilità.

Quindi, se ti ritrovi a implementare il copywriting di qualcun altro nel tuo codice, a scrivere documentazione per altri sviluppatori o addirittura a scrivere UI copia te stesso, tieni presente alcune migliori pratiche fondamentali sull'accessibilità, poiché completano tutti gli altri consigli per la scrittura tecnica.

Cose come:

Andy Bell ne offre alcuni relativamente piccole cose che puoi fare per rendere i contenuti più accessibili, e vale la pena dedicare del tempo a verificarli. E, giusto per divertimento, John Rhea mostra alcuni trucchi di editing accurati ciò è possibile quando lavoriamo con elementi HTML semantici.

Conclusione

Erano sei modi che dimostrano come la scrittura tecnica e lo sviluppo coincidano. Anche se gli esempi e i consigli potrebbero non essere fantascientifici, spero che li abbiate trovati utili, sia che si tratti di collaborare con altri sviluppatori, di mantenere il proprio lavoro, di dover scrivere la propria copia in un attimo o addirittura di abbozzare una proposta di progetto, tra le altre cose. cose.

In conclusione: affinare le tue capacità di scrittura e dedicare un piccolo sforzo extra alla tua scrittura può effettivamente renderti uno sviluppatore migliore.

Risorse di scrittura tecnica

Se sei interessato alla scrittura tecnica:

Se sei interessato al copywriting:

Se sei interessato alla microcopia:

Se sei interessato a utilizzare una guida di stile professionale per migliorare la tua scrittura:

Se sei interessato a scrivere per l'accessibilità:

Timestamp:

Di più da Trucchi CSS