Tekniskt skrivande för utvecklare

HTML, CSS, JavaScript, Python, PHP, C++, Dart — det finns så många programmeringsspråk där ute och du kanske till och med är helt flytande i flera av dem! Men när vi strävar efter att skriva mer och bättre kod, blir sättet vi skriver och kommunicerar i vardagsspråket viktigare och viktigare... och kanske till och med förbises.

Sättet vi skriver om och kring kod är utan tvekan lika viktigt som själva koden. Och trots var du faller på den linjen kan vi alla hålla med om att våra ord har potential att både hjälpa och skada kodens effektivitet.

I den här artikeln vill jag beskriva hur dessa två till synes distinkta områden – programmering och skrivande – kan mötas och ta våra utvecklarfärdigheter till nästa nivå.

Vänta, teknisk skrift? Ja, det är precis vad jag menar. Jag tror verkligen att vi alla är författare i en eller annan mening. Och jag är här för att ge dig en primer med skrivtips, råd och exempel för hur det kan göra dig både till en bättre utvecklare och kommunikatör.

Tekniskt skrivande finns överallt

Förra året, teamet bakom den populära Mac Git-klienten, Tower, tillfrågade mer än 4,000 XNUMX utvecklare och fann att nästan 50 % av dem spenderade mellan 3-6 timmar om dagen på att skriva kod.

Och ja, det är en undersökning som undersökningar en ganska nischgrupp, men jag antar att många av oss hamnar någonstans i det intervallet. Hur som helst, en utvecklare skriver inte kod dygnet runt, för som den här enkäten antyder så lägger vi mycket tid på att göra andra saker.

Det kan inkludera:

• demonstrera en ny funktion,
• dokumentera den nya funktionen,
• uppdatera en arbetsbiljett relaterad till den nya funktionen, eller
• backloggningsarbete för att stödja den nya funktionen.

Naturligtvis finns det alltid tid för badrumspauser och Wordle också.

Hur som helst, de flesta saker vi vanligtvis gör involverar att kommunicera med människor som ditt team, kollegor, kunder, användare och andra utvecklare.

Så vi spenderar en stor del av vår tid på att kommunicera med människor ord utöver den kommunikation vi har med datorer genom koda. Ord är skriftspråk. Och om vi skrev våra ord bättre, skulle vi kommunicera bättre. När vi kommunicerar bättre är det mer sannolikt att vi får det vi vill ha.

Det är Technical Writing 101.

Och det slutar inte ens här.. Vissa programmerare gillar också att göra sina egna produkter, vilket innebär att de måste göra marknadsföring till en del av sitt jobb. Tekniskt skrivande spelar också en stor roll i det. Så ja. Jag tycker att det är ganska rättvist att säga att tekniskt skrivande är det ja allt.

Vad är bra grammatik?

Med så många programmeringsspråk där ute är det sista vi vill lära oss ett till.

Grammatik är en integrerad del av engelska, och det låser upp kommunikationens fulla potential. Det gör oss mer formella, professionella och sammanhängande.

Låt mig ge dig en snabb genomgång av språket.

Den engelska syntaxen

Precis som programmeringsspråk har engelska en väldefinierad syntax, och den börjar med ord.

Ord är byggstenarna i engelska, och de faller i åtta hinkar:

Tänk på dessa som UI komponenter: de är modulära delar som du kan flytta runt för att konstruera en komplett och robust mening, på samma sätt som du kan sätta ihop en komplett och robust UI. Behöver alla komponenter finnas där hela tiden? Absolut inte! Sätt ihop en mening med de bitar du behöver för att slutföra upplevelsen, precis som du skulle göra med ett gränssnitt.

Röst och ton

Ordförråd, skiljetecken, meningsstruktur och ordval. Dessa är alla ingredienserna i engelska. Vi använder dem för att dela idéer, kommunicera med våra vänner och familj och skicka e-postmeddelanden till våra medarbetare.

Men det är viktigt att tänka på låter av våra meddelanden. Det är fantastiskt hur ett utropstecken helt kan ändra tonen i ett meddelande:

1. Jag gillar programmering.
2. I tycka om programmering! :)

Det är lätt att blanda ihop röst för ton, och vice versa.

Röst är det som gäller vårt val av ord, vilket beror på sammanhanget. Till exempel är en handledning för nybörjare mer benägna att använda slang och informellt språk för att förmedla en vänlig röst, medan dokumentation kan skrivas på ett formellt, seriöst och professionellt sätt i ett försök att komma rakt på sak.

Samma meddelande, skrivet med två olika röster:

• Kul: "Utöka ditt sociala nätverk och håll dig uppdaterad om vad som är trendigt nu."
• Allvarlig: "Hitta jobb på en av de största sociala nätverksapparna och jobbmarknaden online."

Det är inte ovanligt att av misstag skriva meddelanden som framstår som nedlåtande, stötande och oprofessionellt. Det är här ton kommer in i bilden. Läs dina meddelanden högt, få andra att läsa dem åt dig och experimentera med din interpunktion och meningsstruktur. Det är så du finslipar din ton.

Här är ett annat sätt att tänka på det: din röst förändras aldrig, men din ton gör det. Din röst är besläktad med vem du är som person, medan tonen är hur du reagerar i en given situation.

Aktiv och passiv röst

En mening innehåller alltid en skådespelare, ett verb och ett mål. Ordningen i vilken dessa kommer avgör om meningen är skriven med en aktiv eller passiv röst.

Skådespelaren kommer först i en aktiv röst. Till exempel: "CSS målar bakgrunden."

Meningar som använder en aktiv röst är enklare än sina motsvarigheter. De är tydligare, kortare och mer begripliga – perfekt för en mer professionell röst som går rakt på sak.

Med en passiv form, skådespelaren kommer sist. (Se vad jag gjorde där?) Det betyder att vår skådespelare - CSS i det här fallet - kommer i slutet så här: "Bakgrunden är målad av CSS."

Läsare konverterar vanligtvis en passiv röst till en aktiv röst i sina huvuden, vilket resulterar i mer bearbetningstid. Om du någonsin har hört att det är bättre att skriva med en aktiv röst, är det oftast anledningen till det. Tekniska skribenter föredrar den aktiva rösten för det mesta, med mycket få undantag som att citera forskning: "Det har föreslagits att ..."

Men det betyder inte att du alltid ska sträva efter en aktiv röst. Att byta från den ena till den andra – även i samma stycke – kan få ditt innehåll att flyta mer sömlöst från en mening till en annan om det används effektivt.

Undvika misstag

Grammatik handlar om språkets struktur och korrekthet, och det finns inget bättre att uppnå det än en snabb korrekturläsning av ditt dokument. Det är mycket viktigt att befria dina skrifter från stavfel, grammatikproblem och semantiska brister.

I slutet av den här artikeln ska jag visa dig de ovärderliga verktyg som proffs använder för att undvika skrivfel. Uppenbarligen finns det inbyggda stavningskontroller i nästan allt nuförtiden; våra kodredigerare har till och med plugins för stavningskontroll och linting för att förhindra misstag. 

Men om du letar efter ett enda verktyg för allt grammatik, Grammarly är ett av de mest använda verktygen. Jag får ingen kickback för det eller så. Det är bara ett riktigt bra verktyg som många redaktörer och skribenter använder för att skriva rent och tydligt innehåll - liknande hur du kan använda Emmet, eslint eller någon annan linter för att skriva ren och tydlig kod.

Skriver kodkommentarer

De saker vi skriver för andra utvecklare kan ha stor inverkan på den övergripande kvaliteten på vårt arbete, oavsett om det är vad vi skriver i koden, hur vi förklarar koden eller hur vi ger feedback på en bit kod.

Det är intressant att varje programmeringsspråk kommer med en standarduppsättning funktioner för att skriva en kommentar. De bör förklara vad koden gör. Med det menar jag inte vaga kommentarer som denna:

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

Använd istället kommentarer som ger mer information:

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

Allt handlar om sammanhang. "Vilken typ av program bygger jag?" är precis den typ av fråga du borde ställa dig själv.

Kommentarer bör ge ett mervärde

Innan vi tittar på vad som gör en "bra" kodkommentar, här är två exempel på lata kommentarer:

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

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

Kom ihåg att syftet med en kommentar är att tillföra värde till en kodbit, inte att upprepa den. Om du inte kan göra det är det bättre att bara lämna koden som den är. Det som gör dessa exempel "lata" är att de bara upprepar vad koden uppenbarligen gör. I det här fallet är kommentarerna överflödiga eftersom de berättar vad vi redan vet – de tillför inget värde!

Kommentarer bör återspegla den aktuella koden

Inaktuella kommentarer är ingen ovanlig syn i stora projekt; vågar jag säga in mest projekt.

Låt oss föreställa oss David, en programmerare och en cool kille att umgås med. David vill sortera en lista med strängar alfabetiskt från A till Ö, så han gör det självklara i JavaScript:

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

David inser då att sortWords() faktiskt sorterar listor från Z till A. Det är inget problem, eftersom han helt enkelt kan vända utdata:

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

Tyvärr uppdaterade inte David sin kodkommentar.

Föreställ dig nu att jag inte berättade den här historien, och allt du såg var koden ovan. Du skulle naturligtvis tro att efter att ha kört den andra kodraden, skulle "städer" sorteras från Ö till A! Hela detta förvirringsfiasko orsakades av en inaktuell kommentar.

Även om detta kan vara ett överdrivet exempel, kan (och ofta gör) något liknande hända om du tävlar mot en nära deadline. Tack och lov kan detta förhindras genom att följa en enkel regel... ändra dina kommentarer samtidigt som du ändrar koden.

Det är en enkel regel som kommer att rädda dig och ditt team från många teknisk skuld.

Nu när vi vet hur dåligt skrivna kommentarer ser ut, låt oss titta på några bra exempel.

Kommentarer bör förklara unidiomatisk kod

Ibland är det naturlig sättet att göra saker är inte rätt. Programmerare kanske måste "bryta" standarderna lite, men när de gör det är det lämpligt att lämna en liten kommentar som förklarar deras motivering:

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

Det är till hjälp, eller hur? Om du var ansvarig för att granska den här koden kan du ha blivit frestad att rätta till den utan att den kommentaren där förklarade vad som hände.

Kommentarer kan identifiera framtida uppgifter

En annan användbar sak att göra med kommentarer är att erkänna att det finns mer arbete att göra.

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

På så sätt kan du behålla fokus på ditt flöde. Och vid ett senare tillfälle kan du (eller någon annan) komma tillbaka och fixa det.

Kommentarer kan länka tillbaka till källan

Så du hittade precis en lösning på ditt problem på StackOverflow. Efter att ha kopierat in den koden är det ibland bra att ha en länk till svaret som hjälpte dig så att du kan komma tillbaka till det för framtida referens.

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

Detta är viktigt eftersom lösningarna kan förändras. Det är alltid bra att veta var din kod kommer ifrån om den någonsin går sönder.

Skriver pull-förfrågningar

Dra förfrågningar (PRs) är en grundläggande aspekt av alla projekt. De sitter i hjärtat av kodrecensioner. Och kodrecensioner kan snabbt bli en flaskhals i ditt lags prestation utan bra formuleringar.

En bra PR beskrivning sammanfattar vad förändring görs och varför det görs. Stora projekt har en pull request-mall, som den här anpassad från en verkligt exempel:

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

Undvik vaga PR titlar

Undvik titlar som ser ut så här:

• Fixa bygget.
• Åtgärda fel.
• Lägg till patch.

Dessa gör inte ens försök för att beskriva vilken build, bugg eller patch det är vi har att göra med. Lite extra detaljer om vilken del av bygget som fixades, vilken bugg som klämdes eller vilken patch som lades till kan räcka långt för att skapa bättre kommunikation och samarbete med dina kollegor. Det nivåsätter och får folk på samma sida.

PR titlar är traditionellt skrivna i imperativ tid. De är en sammanfattning på en rad av det hela PR, och de borde beskriva vad görs av PR.

Här är några bra exempel:

• Stöd anpassade srcset-attribut i NgOptimizedImage
• Standardbildkonfiguration till 75 % bildkvalitet
• Lägg till explicita väljare för alla inbyggda ControlValueAccessors

Undvik långa PRs

En stor PR betyder en enorm beskrivning, och ingen vill granska hundratals eller tusentals rader kod, ibland bara för att avfärda det hela!

Istället kan du:

• kommunicera med ditt team genom Frågor,
• göra en plan,
• bryt ner problemet i mindre bitar, eller
• arbeta på varje del separat med sin egen PR.

Är det inte mycket renare nu?

Ange detaljer i PR kropp

Till skillnad från PR titel, kroppen är d plats för alla detaljer, inklusive:

• Varför är PR vara klar?
• Varför är detta det bästa tillvägagångssättet?
• Eventuella brister i tillvägagångssättet och idéer för att lösa dem om möjligt
• Bugg- eller biljettnumret, benchmarkresultat osv.

Rapportera fel

Felrapporter är en av de viktigaste aspekterna av alla projekt. Och alla fantastiska projekt bygger på feedback från användare. Vanligtvis, även efter otaliga tester, är det användarna som hittar flest buggar. Användare är också stora idealister, och ibland har de funktionsidéer; snälla lyssna på dem!

För tekniska projekt görs allt det här genom att rapportera problem. En välskriven fråga är lätt för en annan utvecklare att hitta och svara på.

Till exempel kommer de flesta stora projekt med en mall:

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

Samla skärmdumpar

Fånga problemet med din systemets verktyg för skärmtagning.

Om det är en skärmdump av en CLI program, se till att texten är tydlig. Om det är en UI program, se till att skärmdumpen fångar rätt element och tillstånd.

Du kan behöva fånga en faktisk interaktion för att visa problemet. Om så är fallet, försök spela in GIF-filer med ett skärminspelningsverktyg.

Hur man reproducerar problemet

Det är mycket lättare för programmerare att lösa en bugg när den är live på deras dator. Det är därför som ett bra engagemang bör komma med stegen för att exakt återskapa problemet.

Här är ett exempel:

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.

Föreslå en orsak

Det är du som fångade felet, så du kanske kan föreslå några potentiella orsaker till varför det finns där. Kanske inträffar buggen först efter att du stöter på en viss händelse, eller så händer den bara på mobilen.

Det kan inte heller skada att utforska kodbasen och kanske identifiera vad som orsakar problemet. Då kommer ditt ärende att avslutas mycket snabbare och du kommer sannolikt att tilldelas den relaterade PR.

Kommunicera med kunder

Du kanske arbetar som frilansare, eller så är du ledande utvecklare i ett litet team. I båda fallen, låt oss säga att du är ansvarig för gränssnittet med kunder i ett projekt. 

Nu är programmerarens stereotyp att vi är dåliga kommunikatörer. Vi har varit kända för att använda alltför teknisk jargong, berätta för andra vad som är och inte är möjligt och till och med gå i defensiv när någon ifrågasätter vårt tillvägagångssätt.

Så, hur dämpar vi den stereotypen? Fråga kunderna vad de vill ha och lyssna alltid på deras feedback. Så här gör du det.

Ställ rätt frågor

Börja med att se till att du och kunden är på samma sida:

• Vem är din målgrupp?
• Vad är målet med sajten?
• Vem är din närmaste konkurrent och vad gör de rätt?

Att ställa frågor är också ett bra sätt att skriva positivt, särskilt i situationer när du inte håller med en klients feedback eller beslut. Att ställa frågor tvingar den personen att stödja sina egna påståenden snarare än att du attackerar dem genom att försvara din egen position:

• Är du OK med det även om det kommer med en extra prestationskostnad?
• Hjälper flyttningen av komponenten oss att bättre uppnå vårt mål?
• Bra, vem är ansvarig för att underhålla det efter lanseringen? 
• Vet du direkt om kontrasten mellan dessa två färger klarar WCAG AA-standarder?

Frågor är mycket mer oskyldiga och främjar nyfikenhet framför fiendskap.

Sälj dig själv

Om du gör ett erbjudande till en potentiell kund, måste du övertyga dem om att anställa dig. Varför ska kunden välja just dig? Det är viktigt att ange följande:

• Vem är du
• Vad du gör
• Varför du passar bra för jobbet
• Länkar till relevant arbete du har gjort

Och när du väl får jobbet och behöver skriva ett kontrakt, kom ihåg att det inte finns något mer skrämmande innehåll än ett gäng juridiska personer. Även om det är skrivet för designprojekt Kontraktsdödare kan vara en bra utgångspunkt för att skriva något mycket vänligare.

Din uppmärksamhet på detaljer kan vara skillnaden mellan dig och en annan utvecklare som försöker vinna samma projekt. Enligt min erfarenhet kommer kunder lika gärna att anlita en utvecklare de tror att de kommer att trivas med att arbeta med än den som tekniskt sett är mest kompetent eller erfaren för jobbet.

Skriver mikrokopia

Mikrokopia är konsten att skriva användarvänligt UI meddelanden, till exempel fel. Jag slår vad om att det har funnits tillfällen där du som utvecklare var tvungen att skriva felmeddelanden eftersom de lades på backburner hela vägen till starttid.

Det kan vara därför vi ibland ser fel som detta:

Error: Unexpected input (Code 693)

Fel är det sista du vill att dina användare ska ta itu med. Men de händer, och det finns inget vi kan göra åt det. Här är några tips för att förbättra dina mikrokopieringsfärdigheter.

Undvik teknisk jargong

De flesta vet inte vad en server är, medan 100 % av programmerarna gör det. Det är därför det inte är ovanligt att se ovanliga termer skrivna i ett felmeddelande, som API eller "timeout exekvering."

Om du inte har att göra med en teknisk klient eller användarbas är det troligt att de flesta av dina användare inte har gått en kurs i datavetenskap och inte vet hur Internet fungerar och varför en viss sak inte fungerar. Därav felet.

Därför bör ett bra felmeddelande inte förklara varför något gick fel, eftersom sådana förklaringar kan kräva att man använder skrämmande tekniska termer. Det är därför det är väldigt viktigt att undvika att använda teknisk jargong.

Skyll aldrig på användaren

Föreställ dig det här: Jag försöker logga in på din plattform. Så jag öppnar min webbläsare, besöker din webbplats och anger mina uppgifter. Sedan får jag höra: "Din e-postadress/ditt lösenord är felaktigt."

Även om det verkar dramatiskt att tro att det här budskapet är fientligt, får det mig undermedvetet att känna mig dum. Microcopy säger att det aldrig är okej att skylla på användaren. Försök att ändra ditt meddelande till något mindre fingerspetsigt, som det här exemplet anpassat från Mailchimps inloggning: "Tyvärr, den e-post-lösenordskombinationen är inte rätt. Vi kan hjälpa dig att återställa ditt konto."

Jag skulle också vilja lägga till vikten av att undvika ALLA BOSTAVER och utropstecken! Visst kan de användas för att förmedla spänning, men i mikrokopia skapar de en känsla av fientlighet mot användaren.

Överväldiga inte användaren

Att använda humor i din mikrokopia är en bra idé! Det kan lätta upp stämningen, och det är ett enkelt sätt att stävja negativiteten som orsakas av även de värsta felen.

Men om du inte använder den perfekt, kan det framstå som nedlåtande och förolämpande för användaren. Det är bara en stor risk att ta.

Mailchimp säger det bra:

Gå inte ur vägen för att skämta - påtvingad humor kan vara värre än ingen alls. Om du är osäker, håll ett rakt ansikte.

(Betonar min)

Skriver tillgänglig markering

Vi skulle lätt kunna spendera en hel artikel om tillgänglighet och hur det relaterar till tekniskt skrivande. Heck, tillgänglighet ingår ofta i innehållsstilsguider, inklusive de för Microsoft och Mailchimp.

Du är en utvecklare och vet förmodligen redan så mycket om tillgänglighet. Du kanske till och med är en av de flitigare utvecklarna som gör tillgänglighet till en central del av ditt arbetsflöde. Ändå är det otroligt hur ofta tillgänglighetsöverväganden sätts på sparlåga, oavsett hur viktigt vi alla vet att det är att göra tillgängliga onlineupplevelser som inkluderar alla förmågor.

Så om du kommer på dig själv implementera någon annans copywriting i din kod, skriva dokumentation för andra utvecklare eller till och med skriva UI kopiera dig själv, tänk på några grundläggande bästa metoder för tillgänglighet, eftersom de avrundar alla andra råd för tekniskt skrivande.

Saker som:

Andy Bell erbjuder några relativt små saker du kan göra för att göra innehåll mer tillgängligt, och det är värt din tid att kolla in dem. Och, bara för sparkar, John Rhea visar upp några snygga redigeringsknep som är möjliga när vi arbetar med semantiska HTML-element.

Slutsats

Det var sex sätt som visar hur tekniskt skrivande och utveckling sammanfaller. Även om exemplen och råden kanske inte är raketvetenskap, hoppas jag att du tyckte att de var användbara, oavsett om det handlar om att samarbeta med andra utvecklare, underhålla ditt eget arbete, behöva skriva din egen kopia i ett nafs, eller till och med utarbeta ett projektförslag, bland annat saker.

Summan av kardemumman: att vässa din skrivförmåga och lägga lite extra ansträngning på ditt skrivande kan faktiskt göra dig till en bättre utvecklare.

Tekniska skrivresurser

Om du är intresserad av tekniskt skrivande:

Om du är intresserad av copywriting:

Om du är intresserad av mikrokopia:

Om du är intresserad av att använda en professionell stilguide för att förbättra ditt skrivande:

Om du är intresserad av att skriva för tillgänglighet: