Teknisk skrivning for udviklere

HTML, CSS, JavaScript, Python, PHP, C++, Dart - der er så mange programmeringssprog derude, og du kan endda være fuldstændig flydende i flere af dem! Men efterhånden som vi sigter efter at skrive mere og bedre kode, bliver måden, vi skriver og kommunikerer på i dagligdags sprog, vigtigere og vigtigere... og måske endda overset.

Måden vi skriver om og omkring kode er uden tvivl lige så vigtig som selve koden. Og på trods af hvor du falder på den linje, kan vi alle være enige om, at vores ord har potentialet til både at hjælpe og skade kodeks effektivitet.

I denne artikel vil jeg skitsere, hvordan disse to tilsyneladende adskilte felter - programmering og skrivning - kan komme sammen og tage vores udviklerfærdigheder til næste niveau.

Vent, teknisk skrivning? Ja, det er præcis det, jeg mener. Jeg tror virkelig på, at vi alle er forfattere i en eller anden forstand. Og jeg er her for at give dig en grundbog med skrivetips, råd og eksempler til, hvordan det kan gøre dig både til en bedre udvikler og formidler.

Teknisk skrivning er overalt

Sidste år stod holdet bag den populære Mac Git-klient, Tower, spurgte mere end 4,000 udviklere og fandt ud af, at næsten 50 % af dem brugte mellem 3-6 timer om dagen på at skrive kode.

Og ja, det er en undersøgelse, der undersøger en temmelig nichegruppe, men jeg forestiller mig, at mange af os falder et sted i det område. Uanset hvad, så skriver en udvikler ikke kode 24/7, for som denne meningsmåling antyder, bruger vi masser af tid på at gøre andre ting.

Det kan omfatte:

• demo en ny funktion,
• dokumenterer den nye funktion,
• opdatering af en arbejdsbillet relateret til den nye funktion, eller
• backlogging arbejde for at understøtte den nye funktion.

Selvfølgelig er der altid tid til badepauser og Wordle også.

I hvert fald involverer de fleste af de ting, vi typisk gør, at kommunikere med folk som dit team, kolleger, kunder, brugere og andre udviklere.

Så vi bruger en god del af vores tid på at kommunikere med mennesker igennem ord ud over den kommunikation vi har med computere igennem kode. Ord er skriftsprog. Og hvis vi skrev vores ord bedre, ville vi kommunikere bedre. Når vi kommunikerer bedre, er der større sandsynlighed for, at vi får det, vi ønsker.

Det er teknisk skrivning 101.

Og det slutter ikke engang her. Nogle programmører kan også godt lide at lave deres egne produkter, hvilket betyder, at de skal gøre markedsføring til en del af deres job. Teknisk skrivning spiller også en stor rolle i det. Så ja. Jeg synes, det er ret rimeligt at sige, at teknisk skrivning er faktisk overalt.

Hvad er god grammatik?

Med så mange programmeringssprog derude, er det sidste, vi ønsker, at lære et andet.

Grammatik er en integreret del af engelsk, og det frigør kommunikationens fulde potentiale. Det gør os mere formelle, professionelle og sammenhængende.

Lad mig give dig en hurtig gennemgang af sproget.

Den engelske syntaks

Ligesom programmeringssprog har engelsk en veldefineret syntaks, og den starter med ord.

Ord er byggestenene i engelsk, og de falder i otte spande:

Tænk på disse som UI komponenter: de er modulære stykker, du kan flytte rundt for at konstruere en komplet og robust sætning, på samme måde som du kan sammensætte en komplet og robust UI. Skal alle komponenterne være der hele tiden? Bestemt ikke! Saml en sætning med de stykker, du skal bruge for at fuldføre oplevelsen, ligesom du ville gøre med en grænseflade.

Stemme og tone

Ordforråd, tegnsætning, sætningsstruktur og ordvalg. Disse er alle ingredienserne i engelsk. Vi bruger dem til at dele ideer, kommunikere med vores venner og familie og sende e-mails til vores kolleger.

Men det er afgørende at overveje lyd af vores beskeder. Det er utroligt, hvordan et udråbstegn fuldstændig kan ændre tonen i en besked:

1. Jeg kan godt lide at programmere.
2. I ligesom programmering! :)

Det er let at forveksle stemme for tone, og omvendt.

Voice er det, der vedrører vores ordvalg, som afhænger af konteksten. For eksempel er en tutorial for begyndere mere tilbøjelige til at bruge slang og uformelt sprog til at formidle en venlig stemme, hvorimod dokumentation kan være skrevet på en formel, seriøs og professionel måde i et forsøg på at komme direkte til sagen.

Den samme besked, skrevet med to forskellige stemmer:

• Sjov: "Udvid dit sociale netværk, og hold dig opdateret om, hvad der er trending nu."
• Alvorlig: "Find job på en af ​​de største sociale netværksapps og online jobmarkeder."

Det er ikke usædvanligt ved et uheld at skrive beskeder, der fremstår som nedladende, stødende og uprofessionelle. Det er her tone kommer i spil. Læs dine beskeder højt, få andre til at læse dem for dig, og eksperimentere med din tegnsætning og sætningsstruktur. Sådan finpudser du din tone.

Her er en anden måde at tænke på: din stemme ændrer sig aldrig, men din tone gør det. Din stemme er beslægtet med, hvem du er som person, mens tone er, hvordan du reagerer i en given situation.

Aktiv og passiv stemme

En sætning indeholder altid en skuespiller, et verbum og et mål. Rækkefølgen, hvori disse kommer, afgør, om sætningen er skrevet med en aktiv eller passiv stemme.

Skuespilleren kommer først i en aktiv stemme. For eksempel: "CSS maler baggrunden."

Sætninger, der bruger en aktiv stemme, er mere ligetil end deres modstykker. De er klarere, kortere og mere forståelige – perfekt til en mere professionel stemme, der kommer lige til sagen.

Med en passiv stemme, kommer skuespilleren sidst. (Se, hvad jeg lavede der?) Det betyder, at vores skuespiller - CSS i dette tilfælde - kommer til sidst sådan her: "Baggrunden er malet af CSS."

Læsere konverterer normalt en passiv stemme til en aktiv stemme i deres hoveder, hvilket resulterer i mere behandlingstid. Hvis du nogensinde har hørt, at det er bedre at skrive med en aktiv stemme, er dette som regel grunden. Tekniske forfattere foretrækker den aktive stemme det meste af tiden, med meget få undtagelser, såsom at citere forskning: "Det er blevet foreslået, at ..."

Men det betyder ikke, at du altid skal stræbe efter en aktiv stemme. Skift fra den ene til den anden - selv i samme afsnit - kan få dit indhold til at flyde mere problemfrit fra en sætning til en anden, hvis det bruges effektivt.

Undgå fejl

Grammatik handler om sprogets struktur og korrekthed, og der er ikke noget bedre at opnå det end en hurtig korrekturlæsning af dit dokument. Det er meget vigtigt at befri dine skrifter for stavefejl, grammatikproblemer og semantiske ufuldkommenheder.

I slutningen af ​​denne artikel vil jeg vise dig de uvurderlige værktøjer, som fagfolk bruger til at undgå skrivefejl. Det er klart, at der er indbygget stavekontrol i næsten alt i disse dage; vores kodeeditorer har endda stavekontrol og linting-plugins for at forhindre fejl. 

Men hvis du leder efter et one-stop-værktøj til grammatik, Grammarly er et af de mest udbredte værktøjer. Jeg får ikke et tilbageslag for det eller noget. Det er bare et rigtig godt værktøj, som mange redaktører og skribenter bruger til at skrive rent og klart indhold - svarende til, hvordan du kan bruge Emmet, eslint eller enhver anden linter til at skrive ren og klar kode.

Skrive kodekommentarer

De ting vi skriver til andre udviklere kan have stor indflydelse på den overordnede kvalitet af vores arbejde, hvad enten det er hvad vi skriver i koden, hvordan vi forklarer koden, eller hvordan vi giver feedback på et stykke kode.

Det er interessant, at hvert programmeringssprog kommer med et standardsæt af funktioner til at skrive en kommentar. De bør forklare, hvad koden gør. Med det mener jeg ikke vage kommentarer som denne:

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

Brug i stedet kommentarer, der giver flere oplysninger:

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

Det hele handler om kontekst. "Hvilken slags program bygger jeg?" er præcis den slags spørgsmål, du bør stille dig selv.

Kommentarer bør tilføje værdi

Før vi ser på, hvad der gør en "god" kodekommentar, er her to eksempler på dovne kommentarer:

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

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

Husk, at formålet med en kommentar er at tilføje værdi til et stykke kode, ikke at gentage det. Hvis du ikke kan gøre det, er det bedre at lade koden være som den er. Det, der gør disse eksempler "dovne", er, at de blot gentager, hvad koden åbenlyst gør. I dette tilfælde er kommentarerne overflødige, fordi de fortæller os, hvad vi allerede ved - de tilføjer ikke værdi!

Kommentarer skal afspejle den aktuelle kode

Forældede kommentarer er ikke noget sjældent syn i store projekter; tør jeg sige ind mest projekter.

Lad os forestille os David, en programmør og en helt igennem cool fyr at hænge ud med. David vil sortere en liste over strenge alfabetisk fra A til Z, så han gør det åbenlyse i JavaScript:

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

David indser så, at sortWords() faktisk sorterer lister fra Z til A. Det er ikke et problem, da han blot kan vende outputtet:

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

Desværre opdaterede David ikke sin kodekommentar.

Forestil dig nu, at jeg ikke fortalte dig denne historie, og alt du så var koden ovenfor. Du skulle naturligvis tro, at efter at have kørt den anden kodelinje, ville 'byer' blive sorteret fra Z til A! Hele denne forvirringsfiasko var forårsaget af en forældet kommentar.

Selvom dette kan være et overdrevet eksempel, kan (og ofte sker) noget lignende ske, hvis du kører mod en tæt deadline. Heldigvis kan dette forhindres ved at følge en simpel regel... ændre dine kommentarer samtidig med, at du ændrer koden.

Det er en simpel regel, der vil spare dig og dit team fra en masse teknisk gæld.

Nu hvor vi ved, hvordan dårligt skrevne kommentarer ser ud, lad os se på nogle gode eksempler.

Kommentarer skal forklare unidiomatisk kode

Nogle gange er det naturlig måden at gøre tingene på er ikke rigtig. Programmører er måske nødt til at "bryde" standarderne en smule, men når de gør det, er det tilrådeligt at efterlade en lille kommentar, der forklarer deres begrundelse:

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

Det er nyttigt, ikke? Hvis du var ansvarlig for at gennemgå denne kode, er du måske blevet fristet til at rette den uden at den kommentar der forklarer, hvad der er galt.

Kommentarer kan identificere fremtidige opgaver

En anden nyttig ting at gøre med kommentarer er at indrømme, at der er mere arbejde at gøre.

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

På denne måde kan du holde fokus på dit flow. Og på et senere tidspunkt kan du (eller en anden) komme tilbage og ordne det.

Kommentarer kan linke tilbage til kilden

Så du har lige fundet en løsning på dit problem på StackOverflow. Efter at have kopieret den kode, er det nogle gange en god ting at beholde et link til det svar, der hjalp dig, så du kan vende tilbage til det til fremtidig reference.

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

Det er vigtigt, fordi løsninger kan ændre sig. Det er altid godt at vide, hvor din kode kommer fra, hvis den nogensinde går i stykker.

Skrive pull requests

Træk anmodninger (PRs) er et grundlæggende aspekt af ethvert projekt. De sidder i hjertet af kodeanmeldelser. Og kodegennemgange kan hurtigt blive en flaskehals i dit holds præstationer uden gode formuleringer.

En god PR beskrivelse opsummerer det forandring bliver lavet og hvorfor det bliver lavet. Store projekter har en pull request skabelon, som denne tilpasset fra en rigtigt eksempel:

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

Undgå vagt PR titler

Undgå venligst titler, der ser sådan ud:

• Ret build.
• Ret fejl.
• Tilføj patch.

Disse gør ikke engang forsøg for at beskrive hvilken build, fejl eller patch det er vi har med at gøre. En lille ekstra detalje om, hvilken del af bygningen der blev rettet, hvilken fejl der blev squashed, eller hvilken patch der blev tilføjet, kan være med til at etablere bedre kommunikation og samarbejde med dine kolleger. Det niveau-sætter og får folk på samme side.

PR titler er traditionelt skrevet i imperativ tid. De er et resumé på én linje af det hele PR, og de skal beskrive det bliver udført af PR.

Her er nogle gode eksempler:

• Understøtter brugerdefinerede srcset-attributter i NgOptimizedImage
• Standard billedkonfiguration til 75 % billedkvalitet
• Tilføj eksplicitte vælgere til alle indbyggede ControlValueAccessors

Undgå lang PRs

En stor PR betyder en enorm beskrivelse, og ingen ønsker at gennemgå hundredvis eller tusindvis af linjer kode, nogle gange bare for at ende med at afvise det hele!

I stedet kunne du:

• kommunikere med dit team gennem Issues,
• lav en plan,
• bryde problemet ned i mindre stykker, eller
• arbejde på hvert stykke separat med sit eget PR.

Er det ikke meget renere nu?

Angiv detaljer i PR krop

i modsætning til den PR titel, kroppen er og plads til alle detaljer, herunder:

• Hvorfor er PR være færdig?
• Hvorfor er dette den bedste tilgang?
• Eventuelle mangler ved tilgangen, og ideer til at løse dem, hvis det er muligt
• Fejlen eller billetnummeret, benchmarkresultater osv.

Rapportering af fejl

Fejlrapporter er et af de vigtigste aspekter af ethvert projekt. Og alle fantastiske projekter er bygget på brugerfeedback. Normalt, selv efter utallige test, er det brugerne, der finder flest fejl. Brugere er også store idealister, og nogle gange har de idéer til funktioner; lyt venligst til dem!

For tekniske projekter udføres alt dette ved at rapportere problemer. Et velskrevet problem er let for en anden udvikler at finde og reagere på.

For eksempel følger de fleste store projekter med en skabelon:

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

Saml skærmbilleder

Fang problemet ved hjælp af din systemets skærmoptagelsesværktøj.

Hvis det er et skærmbillede af en CLI program, skal du sørge for, at teksten er klar. Hvis det er en UI program, skal du sørge for, at skærmbilledet fanger de rigtige elementer og tilstande.

Du skal muligvis fange en faktisk interaktion for at demonstrere problemet. Hvis det er tilfældet, så prøv at optag GIF'er ved hjælp af et skærmoptagelsesværktøj.

Sådan genskabes problemet

Det er meget nemmere for programmører at løse en fejl, når den er live på deres computer. Derfor bør en god commit komme med trinene til præcist at reproducere problemet.

Her er et eksempel:

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.

Foreslå en årsag

Det er dig, der har fanget fejlen, så måske kan du foreslå nogle potentielle årsager til, hvorfor den er der. Måske sker fejlen først, efter du støder på en bestemt begivenhed, eller måske sker den kun på mobilen.

Det kan heller ikke skade at udforske kodebasen og måske identificere, hvad der forårsager problemet. Derefter vil din udgave blive lukket meget hurtigere, og du vil sandsynligvis blive tildelt den relaterede PR.

Kommunikerer med kunder

Du kan arbejde som solo freelancer, eller måske er du hovedudvikler på et lille team. Lad os i begge tilfælde sige, at du er ansvarlig for at kommunikere med kunder på et projekt. 

Nu er programmørens stereotype, at vi er dårlige kommunikatører. Vi har været kendt for at bruge alt for teknisk jargon, fortælle andre, hvad der er og ikke er muligt, og endda blive defensive, når nogen stiller spørgsmålstegn ved vores tilgang.

Så hvordan afbøder vi den stereotype? Spørg kunderne, hvad de vil have, og lyt altid til deres feedback. Sådan gør du det.

Stil de rigtige spørgsmål

Start med at sikre dig, at du og klienten er på samme side:

• Hvem er din målgruppe?
• Hvad er målet med siden?
• Hvem er din nærmeste konkurrent, og hvad gør de rigtigt?

At stille spørgsmål er også en god måde at skrive positivt på, især i situationer, hvor du er uenig i en klients feedback eller beslutning. At stille spørgsmål tvinger den person til at støtte deres egne påstande i stedet for at du angriber dem ved at forsvare din egen holdning:

• Er du okay med det, selvom det kommer med en ekstra ydelsesomkostning?
• Hjælper flytning af komponenten os til bedre at nå vores mål?
• Godt, hvem er ansvarlig for at vedligeholde det efter lanceringen? 
• Ved du umiddelbart, om kontrasten mellem disse to farver lever op til WCAG AA-standarderne?

Spørgsmål er meget mere uskyldige og fremmer nysgerrighed over fjendskab.

Sælg dig selv

Hvis du laver et pitch til en potentiel kunde, bliver du nødt til at overbevise dem om at ansætte dig. Hvorfor skal kunden vælge dig? Det er vigtigt at specificere følgende:

• Hvem er du
• Hvad du gør
• Hvorfor du passer godt til jobbet
• Links til relevant arbejde, du har udført

Og når du først har fået jobbet og skal skrive en kontrakt, så husk, at der ikke er noget indhold, der er mere skræmmende end en flok juridiske personer. Selvom det er skrevet til designprojekter, er det Kontraktsmorder kan være et godt udgangspunkt for at skrive noget meget venligere.

Din opmærksomhed på detaljer kan være forskellen mellem dig og en anden udvikler, der prøver at vinde det samme projekt. Min erfaring er, at kunderne lige så nemt vil ansætte en udvikler, de tror, ​​de vil nyde at arbejde med, end den, der teknisk set er den mest kompetente eller erfarne til jobbet.

Skrive mikrokopi

Mikrokopi er kunsten at skrive brugervenligt UI meddelelser, såsom fejl. Jeg vil vædde på, at der har været tidspunkter, hvor du som udvikler var nødt til at skrive fejlmeddelelser, fordi de blev sat på backburner hele vejen til starttidspunktet.

Det kan være grunden til, at vi nogle gange ser fejl som denne:

Error: Unexpected input (Code 693)

Fejl er det sidste, du vil have dine brugere til at håndtere. Men de sker, og der er intet, vi kan gøre ved det. Her er nogle tips til at forbedre dine mikrokopifærdigheder.

Undgå teknisk jargon

De fleste mennesker ved ikke, hvad en server er, mens 100 % af programmørerne gør det. Derfor er det ikke usædvanligt at se usædvanlige udtryk skrevet i en fejlmeddelelse, som f.eks API eller "timeout-udførelse".

Medmindre du har at gøre med en teknisk klient eller brugerbase, er det sandsynligt, at de fleste af dine brugere ikke har taget et datalogi-kursus og ikke ved, hvordan internettet fungerer, og hvorfor en bestemt ting ikke virker. Derfor fejlen.

Derfor bør en god fejlmeddelelse ikke forklare hvorfor noget gik galt, fordi sådanne forklaringer kan kræve brug af skræmmende tekniske termer. Derfor er det meget vigtigt at undgå at bruge teknisk jargon.

Giv aldrig brugeren skylden

Forestil dig dette: Jeg prøver at logge ind på din platform. Så jeg åbner min browser, besøger din hjemmeside og indtaster mine oplysninger. Så får jeg at vide: "Din e-mail/adgangskode er forkert."

Selvom det virker dramatisk at tro, at dette budskab er fjendtligt, får det mig ubevidst til at føle mig dum. Mikrokopi siger, at det aldrig er okay at give brugeren skylden. Prøv at ændre din besked til noget mindre fingerspids, som dette eksempel, der er tilpasset fra Mailchimps login: “Beklager, den e-mail-adgangskodekombination er ikke rigtig. Vi kan hjælpe dig med at gendanne din konto."

Jeg vil også gerne tilføje vigtigheden af ​​at undgå ALLE BOGSTAVER og udråbstegn! Nok kan de bruges til at formidle begejstring, men i mikrokopi skaber de en følelse af fjendtlighed over for brugeren.

Overvæld ikke brugeren

At bruge humor i din mikrokopi er en god idé! Det kan lette stemningen, og det er en nem måde at dæmme op for negativiteten forårsaget af selv de værste fejl.

Men hvis du ikke bruger det perfekt, kan det virke nedladende og fornærmende for brugeren. Det er bare en big risiko at tage.

Mailchimp siger det godt:

Gå ikke af vejen for at lave en vittighed – tvungen humor kan være værre end ingen overhovedet. Hvis du er usikker, så hold et oprejst ansigt.

(Fremhæv min)

Skrive tilgængelig markup

Vi kunne sagtens bruge en hel artikel om tilgængelighed, og hvordan det relaterer sig til teknisk skrivning. For pokker, tilgængelighed er ofte inkluderet i indholdsstilguider, inklusive dem til microsoft , MailChimp.

Du er udvikler og ved sikkert allerede så meget om tilgængelighed. Du er måske endda en af ​​de mere flittige udviklere, der gør tilgængelighed til en kernedel af din arbejdsgang. Alligevel er det utroligt, hvor ofte tilgængelighedshensyn lægges på bagen, uanset hvor vigtigt vi alle ved, det er at gøre tilgængelige onlineoplevelser, der omfatter alle evner.

Så hvis du finder dig selv at implementere en andens tekstforfatning i din kode, skrive dokumentation til andre udviklere eller endda skrive UI kopier dig selv, vær opmærksom på nogle grundlæggende bedste fremgangsmåder for tilgængelighed, da de afrunder alle de andre råd til teknisk skrivning.

Ting som:

Andy Bell tilbyder nogle relativt små ting, du kan gøre for at gøre indhold mere tilgængeligt, og det er værd at bruge tid på at tjekke dem ud. Og bare for spark, John Rhea viser nogle smarte redigeringstricks det er muligt, når vi arbejder med semantiske HTML-elementer.

Konklusion

Det var seks måder, der demonstrerer, hvordan teknisk skrivning og udvikling falder sammen. Selvom eksemplerne og rådene måske ikke er raketvidenskab, håber jeg, at du fandt dem nyttige, hvad enten det drejer sig om at samarbejde med andre udviklere, vedligeholde dit eget arbejde, at skulle skrive din egen kopi i en knivspids eller endda udarbejde et projektforslag, blandt andet ting.

Den nederste linje: At skærpe dine skrivefærdigheder og lægge lidt ekstra indsats i din skrivning kan faktisk gøre dig til en bedre udvikler.

Tekniske skriveressourcer

Hvis du er interesseret i teknisk skrivning:

Hvis du er interesseret i copywriting:

Hvis du er interesseret i mikrokopi:

Hvis du er interesseret i at bruge en professionel stilguide til at forbedre din skrivning:

Hvis du er interesseret i at skrive for tilgængelighed: