Teknisk skriving for utviklere

HTML, CSS, JavaScript, Python, PHP, C++, Dart — det er så mange programmeringsspråk der ute, og du kan til og med være helt flytende i flere av dem! Men ettersom vi tar sikte på å skrive mer og bedre kode, blir måten vi skriver og kommuniserer på i hverdagsspråket mer og mer viktig ... og kanskje til og med oversett.

Måten vi skriver om og rundt kode er uten tvil like viktig som selve koden. Og til tross for hvor du faller på den linjen, kan vi alle være enige om at ordene våre har potensial til å både hjelpe og skade kodens effektivitet.

I denne artikkelen vil jeg skissere hvordan disse to tilsynelatende forskjellige feltene – programmering og skriving – kan komme sammen og ta utviklerferdighetene våre til neste nivå.

Vent, teknisk skriving? Ja, det er akkurat det jeg mener. Jeg tror virkelig at vi alle er forfattere på en eller annen måte. Og jeg er her for å gi deg en primer med skrivetips, råd og eksempler for hvordan det kan gjøre deg både til en bedre utvikler og formidler.

Teknisk skriving er overalt

I fjor var teamet bak den populære Mac Git-klienten Tower, spurte mer enn 4,000 utviklere og fant ut at nesten 50 % av dem brukte mellom 3-6 timer om dagen på å skrive kode.

Og ja, det er en undersøkelse som viser en ganske nisjegruppe, men jeg ser for meg at mange av oss faller et sted i det området. Uansett, en utvikler skriver ikke kode 24/7, for som denne meningsmålingen antyder, bruker vi mye tid på å gjøre andre ting.

Det kan inkludere:

• demonstrere en ny funksjon,
• dokumenterer den nye funksjonen,
• oppdatere en arbeidsbillett relatert til den nye funksjonen, eller
• backlogging arbeid for å støtte den nye funksjonen.

Selvfølgelig er det alltid tid til baderomspauser og Wordle også.

Uansett, de fleste tingene vi vanligvis gjør involverer å kommunisere med folk som teamet ditt, kolleger, klienter, brukere og andre utviklere.

Så vi bruker en god del av tiden vår på å kommunisere med mennesker gjennom ord i tillegg til kommunikasjonen vi har med datamaskiner gjennom kode. Ord er skriftspråk. Og hvis vi skrev ordene våre bedre, ville vi kommunisert bedre. Når vi kommuniserer bedre, er det mer sannsynlig at vi får det vi ønsker.

Det er teknisk skriving 101.

Og det slutter ikke engang her. Noen programmerere liker også å lage sine egne produkter, noe som betyr at de må gjøre markedsføring til en del av jobben sin. Teknisk skriving spiller en stor rolle i det også. Så ja. Jeg synes det er ganske rettferdig å si at teknisk skriving er det faktisk overalt.

Hva er god grammatikk?

Med så mange programmeringsspråk der ute, er det siste vi ønsker å lære et til.

Grammatikk er en integrert del av engelsk, og den frigjør det fulle potensialet for kommunikasjon. Det gjør oss mer formelle, profesjonelle og sammenhengende.

La meg gi deg en rask oversikt over språk.

Den engelske syntaksen

Akkurat som programmeringsspråk har engelsk en veldefinert syntaks, og den starter med ord.

Ord er byggesteinene i engelsk, og de faller inn i åtte bøtter:

Tenk på disse som UI komponenter: de er modulære deler du kan flytte rundt for å konstruere en komplett og robust setning, på samme måte som du kan sette sammen en komplett og robust UI. Trenger alle komponentene være der hele tiden? Absolutt ikke! Sett sammen en setning med brikkene du trenger for å fullføre opplevelsen, akkurat som du ville gjort med et grensesnitt.

Stemme og tone

Ordforråd, tegnsetting, setningsstruktur og ordvalg. Dette er alle ingrediensene til engelsk. Vi bruker dem til å dele ideer, kommunisere med venner og familie og sende e-poster til kollegene våre.

Men det er viktig å vurdere høres av våre meldinger. Det er utrolig hvordan ett utropstegn fullstendig kan endre tonen i en melding:

1. Jeg liker programmering.
2. I i likhet med programmering! :)

Det er lett å forveksle stemme for tone, og omvendt.

Voice er det som gjelder vårt valg av ord, som avhenger av kontekst. For eksempel er det mer sannsynlig at en opplæring for nybegynnere bruker slang og uformelt språk for å formidle en vennlig stemme, mens dokumentasjon kan være skrevet på en formell, seriøs og profesjonell måte i et forsøk på å komme rett til poenget.

Den samme meldingen, skrevet med to forskjellige stemmer:

• Fun: "Utvid det sosiale nettverket ditt og hold deg oppdatert på hva som er trending nå."
• Seriøs: "Finn jobber på en av de største sosiale nettverksappene og online jobbmarkedet."

Det er ikke uvanlig å ved et uhell skrive meldinger som fremstår som nedlatende, støtende og uprofesjonelle. Dette er hvor tone kommer inn i bildet. Les meldingene dine høyt, få andre til å lese dem for deg, og eksperimentere med tegnsetting og setningsstruktur. Det er hvordan du finpner tonen.

Her er en annen måte å tenke på: stemmen din endres aldri, men tonen din gjør det. Stemmen din er beslektet med hvem du er som person, mens tonen er hvordan du reagerer i en gitt situasjon.

Aktiv og passiv stemme

En setning inneholder alltid en skuespiller, et verb og et mål. Rekkefølgen disse kommer i avgjør om setningen er skrevet med en aktiv eller passiv stemme.

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

Setninger som bruker en aktiv stemme er mer enkle enn sine motstykker. De er klarere, kortere og mer forståelige – perfekt for en mer profesjonell stemme som kommer rett til poenget.

Med en passiv stemme, kommer skuespilleren sist. (Ser du hva jeg gjorde der?) Det betyr at skuespilleren vår - CSS i dette tilfellet - kommer på slutten slik: "Bakgrunnen er malt av CSS."

Lesere konverterer vanligvis en passiv stemme til en aktiv stemme i hodet, noe som resulterer i mer behandlingstid. Hvis du noen gang har hørt at det er bedre å skrive med en aktiv stemme, er dette vanligvis grunnen. Tekniske forfattere foretrekker den aktive stemmen mesteparten av tiden, med svært få unntak som å sitere forskning: "Det har blitt antydet at ..."

Men det betyr ikke at du alltid bør strebe etter en aktiv stemme. Bytte fra den ene til den andre - selv i samme avsnitt - kan få innholdet ditt til å flyte mer sømløst fra en setning til en annen hvis den brukes effektivt.

Unngå feil

Grammatikk handler om strukturen og riktigheten av språket, og det er ingenting bedre å oppnå det enn en rask korrekturlesing av dokumentet ditt. Det er veldig viktig å kvitte seg med skrivefeil, grammatikkproblemer og semantiske ufullkommenheter.

På slutten av denne artikkelen vil jeg vise deg de uvurderlige verktøyene som fagfolk bruker for å unngå skrivefeil. Det er åpenbart innebygde stavekontroller i omtrent alt i disse dager; koderedigererne våre har til og med stavekontroll og linting-plugins for å forhindre feil. 

Men hvis du leter etter et one-stop-verktøy for alt grammatikk, Grammarly er et av de mest brukte verktøyene. Jeg får ikke tilbakeslag for det eller noe. Det er bare et veldig flott verktøy som mange redaktører og skribenter bruker til å skrive rent og tydelig innhold - på samme måte som du kan bruke Emmet, eslint eller hvilken som helst annen linter for å skrive ren og tydelig kode.

Skrive kodekommentarer

Tingene vi skriver for andre utviklere kan ha stor innvirkning på den generelle kvaliteten på arbeidet vårt, enten det er hva vi skriver i koden, hvordan vi forklarer koden, eller hvordan vi gir tilbakemelding på et stykke kode.

Det er interessant at hvert programmeringsspråk kommer med et standard sett med funksjoner for å skrive en kommentar. De bør forklare hva koden gjør. Med det mener jeg ikke vage kommentarer som dette:

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

Bruk heller kommentarer som gir mer informasjon:

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

Alt handler om kontekst. "Hva slags program bygger jeg?" er akkurat den typen spørsmål du bør stille deg selv.

Kommentarer bør tilføre verdi

Før vi ser på hva som gjør en "god" kodekommentar, her er to eksempler på late kommentarer:

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

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

Husk at hensikten med en kommentar er å tilføre verdi til et stykke kode, ikke å gjenta det. Hvis du ikke kan gjøre det, er det bedre å la koden være som den er. Det som gjør disse eksemplene "late" er at de bare gjengir hva koden åpenbart gjør. I dette tilfellet er kommentarene overflødige fordi de forteller oss det vi allerede vet – de tilfører ikke verdi!

Kommentarer skal gjenspeile gjeldende kode

Utdaterte kommentarer er ikke noe sjeldent syn i store prosjekter; tør jeg si i mest prosjekter.

La oss forestille oss David, en programmerer og en allsidig kul fyr å henge med. David ønsker å sortere en liste over strenger alfabetisk fra A til Å, så han gjør det åpenbare i JavaScript:

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

David innser da at sortWords() faktisk sorterer lister fra Å til A. Det er ikke noe problem, siden han ganske enkelt kan reversere utdataene:

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

Dessverre oppdaterte ikke David kodekommentaren sin.

Tenk deg nå at jeg ikke fortalte deg denne historien, og alt du så var koden ovenfor. Du skulle naturligvis tro at etter å ha kjørt den andre kodelinjen, ville "byer" sorteres fra Å til A! Hele denne forvirringsfiaskoen ble forårsaket av en foreldet kommentar.

Selv om dette kan være et overdrevet eksempel, kan (og ofte skjer) noe lignende skje hvis du kjører mot en nær frist. Heldigvis kan dette forhindres ved å følge en enkel regel ... endre kommentarene dine samtidig som du endrer koden.

Det er en enkel regel som vil spare deg og teamet ditt for mye teknisk gjeld.

Nå som vi vet hvordan dårlig skrevne kommentarer ser ut, la oss se på noen gode eksempler.

Kommentarer bør forklare unidiomatisk kode

Noen ganger er det naturlig måten å gjøre ting på er ikke riktig. Programmerere må kanskje "bryte" standardene litt, men når de gjør det, er det tilrådelig å legge igjen en liten kommentar som forklarer begrunnelsen deres:

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

Det er nyttig, ikke sant? Hvis du var ansvarlig for å gjennomgå denne koden, kan du ha blitt fristet til å rette den uten at kommentaren der forklarer hva som skjer.

Kommentarer kan identifisere fremtidige oppgaver

En annen nyttig ting å gjøre med kommentarer er å innrømme at det er mer arbeid å gjøre.

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

På denne måten kan du holde fokus på flyten din. Og på et senere tidspunkt kan du (eller noen andre) komme tilbake og fikse det.

Kommentarer kan lenke tilbake til kilden

Så du har nettopp funnet en løsning på problemet ditt på StackOverflow. Etter å ha kopiert inn den koden, er det noen ganger en god ting å beholde en lenke til svaret som hjalp deg slik at du kan komme tilbake til det for fremtidig referanse.

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

Dette er viktig fordi løsninger kan endres. Det er alltid godt å vite hvor koden din kom fra i tilfelle den noen gang går i stykker.

Skrive pull-forespørsler

Trekk forespørsler (PRs) er et grunnleggende aspekt ved ethvert prosjekt. De sitter i hjertet av kodevurderinger. Og kodevurderinger kan fort bli en flaskehals i teamets ytelse uten gode ordlyder.

En god PR beskrivelse oppsummerer hva endring blir gjort og hvorfor det blir laget. Store prosjekter har en pull request mal, som denne tilpasset fra en ekte 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…

Unngå vage PR titler

Vennligst unngå titler som ser slik ut:

• Fiks bygge.
• Fiks feil.
• Legg til oppdatering.

Disse gjør ikke engang forsøk for å beskrive hvilken build, bug eller patch det er vi har å gjøre med. En liten ekstra detalj om hvilken del av bygget som ble fikset, hvilken feil som ble squashed, eller hvilken oppdatering som ble lagt til kan bidra langt for å etablere bedre kommunikasjon og samarbeid med kollegene dine. Det nivå-setter og får folk på samme side.

PR titler er tradisjonelt skrevet i imperativ tid. De er en enlinjes oppsummering av det hele PR, og de skal beskrive hva gjøres av PR.

Her er noen gode eksempler:

• Støtt tilpassede srcset-attributter i NgOptimizedImage
• Standard bildekonfigurasjon til 75 % bildekvalitet
• Legg til eksplisitte velgere for alle innebygde ControlValueAccessors

Unngå lang PRs

En stor PR betyr en enorm beskrivelse, og ingen ønsker å gjennomgå hundrevis eller tusenvis av linjer med kode, noen ganger bare for å ende opp med å avvise hele greia!

I stedet kan du:

• kommunisere med teamet ditt gjennom Problemer,
• lag en plan,
• bryte ned problemet i mindre biter, eller
• arbeid på hver del separat med sin egen PR.

Er det ikke mye renere nå?

Oppgi detaljer i PR kroppen

I motsetning til PR tittel, kroppen er de plass for alle detaljer, inkludert:

• Hvorfor er PR være ferdig?
• Hvorfor er dette den beste tilnærmingen?
• Eventuelle mangler ved tilnærmingen, og ideer for å løse dem hvis mulig
• Feilen eller billettnummeret, referanseresultater osv.

Rapporterer feil

Feilrapporter er en av de viktigste aspektene ved ethvert prosjekt. Og alle flotte prosjekter er bygget på tilbakemeldinger fra brukere. Vanligvis, selv etter utallige tester, er det brukerne som finner de fleste feilene. Brukere er også gode idealister, og noen ganger har de funksjonsideer; vennligst hør på dem!

For tekniske prosjekter gjøres alt dette ved å rapportere problemer. Et velskrevet problem er lett for en annen utvikler å finne og svare på.

For eksempel følger de fleste store prosjekter med en mal:

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

Samle skjermbilder

Fang problemet med din systemets skjermopptaksverktøy.

Hvis det er et skjermbilde av en CLI program, sørg for at teksten er tydelig. Hvis det er en UI program, sørg for at skjermbildet fanger opp de riktige elementene og tilstandene.

Du må kanskje fange opp en faktisk interaksjon for å demonstrere problemet. Hvis det er tilfelle, prøv å ta opp GIF-er ved hjelp av et skjermopptaksverktøy.

Hvordan gjenskape problemet

Det er mye lettere for programmerere å løse en feil når den er direkte på datamaskinen deres. Det er derfor en god forpliktelse bør komme med trinnene for å gjenskape problemet nøyaktig.

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 årsak

Det var du som fanget feilen, så kanskje du kan foreslå noen potensielle årsaker til hvorfor den er der. Kanskje skjer feilen først etter at du møter en bestemt hendelse, eller kanskje den bare skjer på mobil.

Det kan heller ikke skade å utforske kodebasen, og kanskje identifisere hva som forårsaker problemet. Deretter vil problemet ditt bli lukket mye raskere, og du vil sannsynligvis bli tildelt den relaterte PR.

Kommunisere med kunder

Du kan jobbe som frilanser alene, eller kanskje du er hovedutvikleren i et lite team. I begge tilfeller, la oss si at du er ansvarlig for å kommunisere med klienter på et prosjekt. 

Nå er programmererstereotypen at vi er dårlige kommunikatorer. Vi har vært kjent for å bruke altfor teknisk sjargong, fortelle andre hva som er og ikke er mulig, og til og med bli defensive når noen stiller spørsmål ved vår tilnærming.

Så hvordan kan vi dempe den stereotypen? Spør kundene hva de vil ha, og lytt alltid til tilbakemeldingene deres. Slik gjør du det.

Still de riktige spørsmålene

Start med å sørge for at du og klienten er på samme side:

• Hvem er målgruppen din?
• Hva er målet med siden?
• Hvem er din nærmeste konkurrent og hva gjør de riktig?

Å stille spørsmål er også en god måte å skrive positivt på, spesielt i situasjoner der du er uenig i en klients tilbakemelding eller beslutning. Å stille spørsmål tvinger den personen til å støtte sine egne påstander i stedet for at du angriper dem ved å forsvare din egen posisjon:

• Er du OK med det selv om det kommer med en ekstra ytelseskostnad?
• Hjelper flytting av komponenten oss til å bedre oppnå målet vårt?
• Flott, hvem er ansvarlig for å vedlikeholde det etter lansering? 
• Vet du umiddelbart om kontrasten mellom disse to fargene passer WCAG AA-standardene?

Spørsmål er mye mer uskyldige og fremmer nysgjerrighet fremfor fiendskap.

Selg deg selv

Hvis du gir en pitch til en potensiell kunde, må du overbevise dem om å ansette deg. Hvorfor skal kunden velge deg? Det er viktig å spesifisere følgende:

• Hvem du er
• Hva du gjør
• Hvorfor du passer godt for jobben
• Lenker til relevant arbeid du har utført

Og når du først får jobben og trenger å skrive opp en kontrakt, husk at det ikke er noe innhold som er mer skremmende enn en haug med juridiske personer. Selv om den er skrevet for designprosjekter, er den Avtalemorderen kan være et fint utgangspunkt for å skrive noe mye vennligere.

Din oppmerksomhet på detaljer kan være forskjellen mellom deg og en annen utvikler som prøver å vinne det samme prosjektet. Min erfaring er at klienter like gjerne vil ansette en utviklere de tror de vil trives med enn den som teknisk sett er mest kompetent eller erfaren for jobben.

Skrive mikrokopi

Mikrokopi er kunsten å skrive brukervennlig UI meldinger, for eksempel feil. Jeg vedder på at det har vært tider hvor du som utvikler måtte skrive feilmeldinger fordi de ble satt på bakbrenneren hele veien til lanseringstidspunktet.

Det kan være grunnen til at vi noen ganger ser feil som dette:

Error: Unexpected input (Code 693)

Feil er det siste du vil at brukerne skal håndtere. Men de skjer, og det er ingenting vi kan gjøre med det. Her er noen tips for å forbedre mikrokopieringsferdighetene dine.

Unngå teknisk sjargong

De fleste vet ikke hva en server er, mens 100 % av programmererne gjør det. Det er derfor det ikke er uvanlig å se uvanlige termer skrevet i en feilmelding, som API eller «utførelse av tidsavbrudd».

Med mindre du har å gjøre med en teknisk klient eller brukerbase, er det sannsynlig at de fleste av brukerne dine ikke tok et informatikkkurs og ikke vet hvordan Internett fungerer, og hvorfor en bestemt ting ikke fungerer. Derav feilen.

Derfor bør ikke en god feilmelding forklare hvorfor noe gikk galt, fordi slike forklaringer kan kreve bruk av skumle faguttrykk. Derfor er det veldig viktig å unngå å bruke teknisk sjargong.

Klandre aldri brukeren

Tenk deg dette: Jeg prøver å logge på plattformen din. Så jeg åpner nettleseren min, besøker nettstedet ditt og skriver inn detaljene mine. Så får jeg beskjed: "Din e-postadresse/passord er feil."

Selv om det virker dramatisk å tro at dette budskapet er fiendtlig, får det meg ubevisst til å føle meg dum. Mikrokopi sier at det aldri er greit å skylde på brukeren. Prøv å endre meldingen din til noe mindre fingerspiss, som dette eksemplet tilpasset fra Mailchimps pålogging: "Beklager, den e-post-passordkombinasjonen er ikke riktig. Vi kan hjelpe deg med å gjenopprette kontoen din."

Jeg vil også legge til viktigheten av å unngå STORE STOFFER og utropstegn! Visst, de kan brukes til å formidle spenning, men i mikrokopi skaper de en følelse av fiendtlighet mot brukeren.

Ikke overveld brukeren

Å bruke humor i mikrokopi er en god idé! Det kan lette opp stemningen, og det er en enkel måte å dempe negativiteten forårsaket av selv de verste feilene.

Men hvis du ikke bruker det perfekt, kan det fremstå som nedlatende og fornærmende for brukeren. Det er bare en stor risiko å ta.

Mailchimp sier det godt:

Ikke gå av veien for å lage en vits – tvungen humor kan være verre enn ingen i det hele tatt. Hvis du er usikker, hold ansiktet rett.

(Vekt min)

Skrive tilgjengelig markup

Vi kan enkelt bruke en hel artikkel om tilgjengelighet og hvordan det forholder seg til teknisk skriving. Pokker, tilgjengelighet er ofte inkludert i innholdsstilguider, inkludert de for Microsoft og MailChimp.

Du er en utvikler og vet sannsynligvis allerede så mye om tilgjengelighet. Du kan til og med være en av de mer flittige utviklerne som gjør tilgjengelighet til en sentral del av arbeidsflyten din. Likevel er det utrolig hvor ofte tilgjengelighetshensyn settes på baksiden, uansett hvor viktig vi alle vet det er å gjøre tilgjengelige nettopplevelser som inkluderer alle evner.

Så hvis du finner deg selv å implementere andres copywriting i koden din, skrive dokumentasjon for andre utviklere, eller til og med skrive UI kopier deg selv, vær oppmerksom på noen grunnleggende gode fremgangsmåter for tilgjengelighet, da de avrunder alle andre råd for teknisk skriving.

Ting som:

Andy Bell tilbyr noen relativt små ting du kan gjøre for å gjøre innhold mer tilgjengelig, og det er verdt tiden din å sjekke dem ut. Og, bare for spark, John Rhea viser frem noen smarte redigeringstriks som er mulig når vi jobber med semantiske HTML-elementer.

konklusjonen

Dette var seks måter som demonstrerer hvordan teknisk skriving og utvikling faller sammen. Selv om eksemplene og rådene kanskje ikke er rakettvitenskap, håper jeg at du fant dem nyttige, enten det er å samarbeide med andre utviklere, vedlikeholde ditt eget arbeid, måtte skrive din egen kopi på et blunk, eller til og med utarbeide et prosjektforslag, blant annet tingene.

Hovedpoenget: Å skjerpe skriveferdighetene dine og legge litt ekstra innsats i skrivingen kan faktisk gjøre deg til en bedre utvikler.

Tekniske skriveressurser

Hvis du er interessert i teknisk skriving:

Hvis du er interessert i copywriting:

Hvis du er interessert i mikrokopi:

Hvis du er interessert i å bruke en profesjonell stilguide for å forbedre skrivingen din:

Hvis du er interessert i å skrive for tilgjengelighet: