Tehniline kirjutamine arendajatele

HTML, CSS, JavaScript, Python, PHP, C++, Dart – seal on nii palju programmeerimiskeeli ja võite isegi mõnda neist täiesti vabalt valdada! Kuid kuna meie eesmärk on kirjutada rohkem ja paremat koodi, muutub see, kuidas me igapäevases keeles kirjutame ja suhtleme, üha olulisemaks… ja võib-olla isegi tähelepanuta jäetakse.

See, kuidas me koodist ja selle ümber kirjutame, on vaieldamatult sama oluline kui kood ise. Ja hoolimata sellest, kuhu te sellel joonel langete, võime kõik nõustuda, et meie sõnad võivad koodi tõhusust nii aidata kui ka kahjustada.

Selles artiklis tahan visandada, kuidas need kaks näiliselt erinevat valdkonda – programmeerimine ja kirjutamine – saavad kokku tulla ja viia meie arendajaoskused järgmisele tasemele.

Oot, tehniline kirjutamine? Jah, täpselt seda ma mõtlen. Ma tõesti usun, et me kõik oleme ühes või teises mõttes kirjanikud. Ja ma olen siin, et anda teile aabits, mis sisaldab näpunäiteid, nõuandeid ja näiteid selle kohta, kuidas see võib teid nii paremaks arendajaks kui ka suhtlejaks muuta.

Tehniline kirjutamine on kõikjal

Eelmisel aastal toetas populaarse Mac Giti kliendi Toweri meeskond küsitles enam kui 4,000 arendajat ja leidis, et peaaegu 50% neist kulutas koodi kirjutamisele 3–6 tundi päevas.

Ja jah, see on üks küsitlus üsna niširühmast, kuid ma kujutan ette, et paljud meist jäävad kuhugi sellesse vahemikku. Igal juhul ei kirjuta arendaja koodi 24/7, sest nagu see küsitlus viitab, kulutame palju aega muudele asjadele.

See võib hõlmata järgmist:

• uue funktsiooni demonstreerimine,
• selle uue funktsiooni dokumenteerimine,
• selle uue funktsiooniga seotud tööpileti värskendamine või
• mahajäämustöö selle uue funktsiooni toetamiseks.

Muidugi on alati aega vannitoapauside ja Wordle jaoks.

Igatahes hõlmab enamik asju, mida me tavaliselt teeme, suhtlemist inimestega, nagu teie meeskond, kolleegid, kliendid, kasutajad ja muud arendajad.

Seega kulutame suure osa oma ajast inimestega suhtlemisele sõnad lisaks suhtlemisele arvutitega läbi kood. Sõnad on kirjakeel. Ja kui me oma sõnad paremini kirjutaksime, suhtleksime paremini. Kui me suhtleme paremini, saame tõenäolisemalt selle, mida tahame.

See on tehniline kirjutamine 101.

Ja see ei lõpe isegi siin. Mõnele programmeerijale meeldib ka ise tooteid valmistada, mis tähendab, et nad peavad muutma turunduse oma töö osaks. Ka tehniline kirjutamine mängib selles suurt rolli. Nii, jah. Ma arvan, et on üsna aus öelda, et tehniline kirjutamine on tõepoolest kõikjal.

Mis on hea grammatika?

Kuna seal on nii palju programmeerimiskeeli, siis viimane asi, mida me tahame, on õppida veel üks.

Grammatika on inglise keele lahutamatu osa ja see avab suhtluse täieliku potentsiaali. See muudab meid ametlikumaks, professionaalsemaks ja ühtsemaks.

Lubage mul anda teile kiire ülevaade keelest.

Inglise keele süntaks

Nii nagu programmeerimiskeeltel, on ka inglise keelel täpselt määratletud süntaks ja see algab sõnadega.

Sõnad on inglise keele ehituskivid ja need jagunevad kaheksasse ämbrisse:

Mõelge nendele sarnastele UI komponendid: need on modulaarsed tükid, mida saate liigutada, et luua terviklik ja jõuline lause, samamoodi nagu võite koostada tervikliku ja tugeva lause UI. Kas kõik komponendid peavad kogu aeg olemas olema? Kindlasti mitte! Koostage lause osadest, mida on kogemuse lõpuleviimiseks vaja, täpselt nagu liidese puhul.

Hääl ja toon

Sõnavara, kirjavahemärgid, lauseehitus ja sõnavalik. Need on kõik inglise keele koostisosad. Kasutame neid ideede jagamiseks, sõprade ja perega suhtlemiseks ning töökaaslastele e-kirjade saatmiseks.

Kuid on ülioluline kaaluda heli meie sõnumitest. On hämmastav, kuidas üks hüüumärk võib sõnumi tooni täielikult nihutada:

1. Mulle meeldib programmeerida.
2. I nagu programmeerimine! :)

Häält on lihtne tooniga segi ajada ja vastupidi.

Hääl on see, mis puudutab meie sõnavalikut, mis sõltub kontekstist. Näiteks algajatele mõeldud õpetuses kasutatakse sõbraliku hääle edastamiseks tõenäolisemalt slängi ja mitteametlikku keelt, samas kui dokumentatsioon võib olla kirjutatud ametlikult, tõsiselt ja professionaalselt, et jõuda otse asja juurde.

Sama sõnum, kirjutatud kahe erineva häälega:

• Lõbus: "Laiendage oma suhtlusvõrgustikku ja olge kursis praeguste trendidega."
• Tõsine: "Leidke tööd ühelt suurimalt suhtlusvõrgustikurakenduselt ja veebipõhiselt tööturult."

Pole ebatavaline, et kirjutate kogemata sõnumeid, mis tunduvad halvustavate, solvavate ja ebaprofessionaalsetena. See on koht toon mängib. Lugege oma sõnumeid valjusti, paluge teistel neid enda eest lugeda ning katsetage oma kirjavahemärke ja lauseehitust. Nii lihvid oma tooni.

Siin on veel üks viis, kuidas seda mõelda: teie hääl ei muutu kunagi, kuid teie toon muutub. Teie hääl on sarnane sellele, kes te inimesena olete, samas kui toon on see, kuidas te konkreetses olukorras reageerite.

Aktiivne ja passiivne hääl

Lause sisaldab alati näitlejat, tegusõna ja sihtmärki. Nende saabumise järjekord määrab, kas lause on kirjutatud aktiivse või passiivse häälega.

Näitleja on esikohal aktiivne hääl. Näiteks: "CSS värvib tausta."

Aktiivset häält kasutavad laused on otsekohesemad kui nende kolleegid. Need on selgemad, lühemad ja arusaadavamad – ideaalsed professionaalsema hääle jaoks, mis läheb otse asja juurde.

Mis passiivne hääl, näitleja on viimane. (Vaata, mida ma seal tegin?) See tähendab, et meie näitleja – antud juhul CSS – jõuab lõpus nii: "Tausta maalib CSS."

Tavaliselt muudavad lugejad passiivse hääle oma peas aktiivseks hääleks, mille tulemuseks on rohkem töötlemisaega. Kui olete kunagi kuulnud, et aktiivse häälega kirjutamine on parem, on see tavaliselt põhjus. Tehnikakirjanikud eelistavad enamasti aktiivset häält, välja arvatud väga vähesed erandid, näiteks tsiteerivad uuringuid: "On oletatud, et ..."

Kuid see ei tähenda, et peaksite alati püüdlema aktiivse hääle poole. Ühelt teisele lülitumine – isegi samas lõigus – võib tõhusa kasutamise korral muuta teie sisu sujuvamaks ühest lausest teise.

Vigade vältimine

Grammatika on seotud keele struktuuri ja korrektsusega ning selle saavutamiseks pole midagi paremat kui dokumendi kiire korrektuur. Väga oluline on vabastada oma kirjutistest õigekirjavigadest, grammatikaprobleemidest ja semantilistest puudustest.

Selle artikli lõpus näitan teile hindamatuid tööriistu, mida spetsialistid kirjutamisvigade vältimiseks kasutavad. Ilmselgelt on tänapäeval peaaegu kõiges sisseehitatud õigekirjakontroll; meie koodiredaktoritel on vigade vältimiseks isegi õigekirjakontrolli ja lintimise pistikprogrammid. 

Aga kui otsite universaalset grammatika tööriista, Grammarly on üks enim kasutatavaid tööriistu. Ma ei saa selle eest tagasilööki ega midagi. See on lihtsalt suurepärane tööriist, mida paljud toimetajad ja kirjanikud kasutavad puhta ja selge sisu kirjutamiseks – sarnaselt sellele, kuidas saaksite kasutada Emmetit, Eslinti või mõnda muud linterit puhta ja selge koodi kirjutamiseks.

Koodi kommentaaride kirjutamine

Asjad, mida me teistele arendajatele kirjutame, võivad avaldada suurt mõju meie töö üldisele kvaliteedile, olgu see siis see, mida me koodi kirjutame, kuidas me koodi selgitame või kuidas me koodijupi kohta tagasisidet anname.

Huvitav on see, et igal programmeerimiskeelel on standardsete funktsioonide komplekt kommentaaride kirjutamiseks. Nad peaksid selgitama, mida kood teeb. Selle all ei pea ma silmas selliseid ebamääraseid kommentaare:

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

Selle asemel kasutage rohkem teavet pakkuvaid kommentaare:

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

Kõik sõltub kontekstist. "Millist programmi ma koostan?" on täpselt selline küsimus, mida peaksite endalt küsima.

Kommentaarid peaksid lisama väärtust

Enne kui vaatame, mis teeb "hea" koodikommentaari, on siin kaks näidet laiskadest kommentaaridest:

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

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

Pidage meeles, et kommentaari eesmärk on lisada koodilõigu väärtust, mitte seda korrata. Kui te seda teha ei saa, on parem kood lihtsalt jätta. Need näited teeb "laisaks" see, et nad lihtsalt kordavad seda, mida kood ilmselgelt teeb. Sel juhul on kommentaarid üleliigsed, sest need ütlevad meile seda, mida me juba teame – need ei lisa väärtust!

Kommentaarid peaksid kajastama praegust koodi

Aegunud kommentaarid pole suurte projektide puhul haruldane nähtus; julgen sisse öelda kõige projekte.

Kujutagem ette Davidit, programmeerijat ja igati lahedat meest, kellega koos aega veeta. David soovib sortida stringide loendit tähestikulises järjekorras A-st Z-ni, seega teeb ta JavaScriptis ilmselget:

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

Seejärel mõistab David, et sortWords() sorteerib loendid Z-st A-ni. See pole probleem, kuna ta saab väljundi lihtsalt ümber pöörata:

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

Kahjuks ei värskendanud David oma koodi kommentaari.

Kujutage nüüd ette, et ma ei rääkinud teile seda lugu ja kõik, mida te nägite, oli ülaltoodud kood. Võiks loomulikult arvata, et pärast teise koodirea käivitamist sorteeritakse linnad Z-st A-ni! Kogu selle segaduse fiasko põhjustas ummistunud kommentaar.

Kuigi see võib olla liialdatud näide, võib midagi sarnast juhtuda (ja juhtub sageli), kui võistlete lähedase tähtajaga. Õnneks saab seda vältida, järgides ühte lihtsat reeglit ... muutke oma kommentaare samal ajal, kui muudate koodi.

See on üks lihtne reegel, mis päästab teid ja teie meeskonda paljudest probleemidest tehniline võlg.

Nüüd, kui teame, kuidas halvasti kirjutatud kommentaarid välja näevad, vaatame mõnda head näidet.

Kommentaarid peaksid selgitama unidiomaatilist koodi

Mõnikord loomulik viis asju ajada ei ole õige. Võimalik, et programmeerijad peavad standardeid pisut "rikkuma", kuid kui nad seda teevad, on soovitatav jätta väike kommentaar, mis selgitab nende põhjendust:

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

See on abiks, eks? Kui vastutasite selle koodi ülevaatamise eest, võis teil tekkida kiusatus seda parandada, ilma et see kommentaar oleks lahti seletanud.

Kommentaarid võivad tuvastada tulevasi ülesandeid

Veel üks kasulik asi, mida kommentaaridega teha, on tunnistada, et tööd on rohkem.

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

Nii saate oma voolule keskenduda. Ja hiljem võite teie (või keegi teine) tagasi tulla ja seda parandada.

Kommentaarid võivad viidata allikale

Niisiis, leidsite just oma probleemile lahenduse StackOverflow's. Pärast selle koodi kopeerimist ja kleepimist on mõnikord hea säilitada link vastusele, mis teid aitas, et saaksite selle juurde edaspidiseks viitamiseks tagasi pöörduda.

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

See on oluline, sest lahendused võivad muutuda. Alati on hea teada, kust teie kood tuli, juhuks kui see peaks kunagi purunema.

Tõmbetaotluste kirjutamine

Tõmbenõuded (PRs) on iga projekti põhiaspekt. Nad on koodiülevaatuste keskmes. Ja koodiülevaatustest võib ilma hea sõnastuseta kiiresti saada kitsaskoht teie meeskonna töös.

Hea PR kirjeldus võtab kokku mida muudatus tehakse ja miks seda tehakse. Suurtel projektidel on tõmbepäringu mall, nagu see, mis on kohandatud a tõeline näide:

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

Vältige ebamäärast PR pealkirjad

Vältige pealkirju, mis näevad välja sellised:

• Parandage ehitus.
• Parandage viga.
• Lisa plaaster.

Need isegi mitte katse kirjeldamaks, millise konstruktsiooni, vea või paigaga me tegeleme. Väike lisateave selle kohta, milline osa järgust parandati, milline viga tõrjuti või milline plaaster lisati, võib kolleegidega parema suhtluse ja koostöö loomisel palju kaasa aidata. See seab taseme ja viib inimesed samale lehele.

PR pealkirjad kirjutatakse traditsiooniliselt sisse käskiv aeg. Need on üherealine kokkuvõte tervikust PRja nad peaksid kirjeldama mida seda teeb PR.

Siin on mõned head näited:

• Toetage kohandatud srcset atribuute rakenduses NgOptimizedImage
• Pildi vaikekonfiguratsioon 75% pildikvaliteedile
• Lisage selgesõnalised valijad kõigi sisseehitatud ControlValueAccessorite jaoks

Vältige pikka PRs

Suur PR tähendab tohutut kirjeldust ja keegi ei taha sadu või tuhandeid koodiridu üle vaadata, mõnikord lihtsalt selleks, et kogu asjast loobuda!

Selle asemel võiksite:

• kaudu oma meeskonnaga suhelda Küsimused,
• tee plaan,
• jagage probleem väiksemateks tükkideks või
• töötage iga tükiga eraldi omadega PR.

Kas pole nüüd palju puhtam?

Esitage üksikasjad jaotises PR keha

Erinevalt PR pealkiri, keha on the,en koht kõigi üksikasjade jaoks, sealhulgas:

• Miks see on? PR tehakse?
• Miks on see parim lähenemine?
• Kõik lähenemisviisi puudused ja ideed nende lahendamiseks, kui võimalik
• Vea või pileti number, võrdlusuuringu tulemused jne.

Vigadest teatamine

Veaaruanded on iga projekti üks olulisemaid aspekte. Ja kõik suurepärased projektid on üles ehitatud kasutajate tagasisidele. Tavaliselt leiavad kasutajad isegi pärast lugematuid teste enamiku vigu. Kasutajad on ka suured idealistid ja mõnikord on neil funktsioonide ideid; palun kuulake neid!

Tehniliste projektide puhul tehakse kõik need asjad probleemidest teatamise teel. Hästi kirjutatud probleemi on teisel arendajal lihtne leida ja sellele vastata.

Näiteks enamik suuri projekte tuleb kaasa malli:

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

Koguge ekraanipilte

Jäädvustage probleem oma süsteemi ekraanipildistamise utiliit.

Kui see on ekraanipilt a CLI programmi, veenduge, et tekst oleks selge. Kui see on a UI programmi, veenduge, et ekraanipilt jäädvustaks õiged elemendid ja olekud.

Võimalik, et peate probleemi näitamiseks jäädvustama tegeliku suhtluse. Kui see nii on, proovige salvestage GIF-e ekraanisalvestustööriista abil.

Kuidas probleemi taastoota

Programmeerijatel on palju lihtsam viga lahendada, kui see on nende arvutis reaalajas. Sellepärast peaksid hea pühendumisega kaasnema sammud probleemi täpseks taasesitamiseks.

Siin on näide:

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.

Soovitage põhjust

Teie olete see, kes vea tabas, nii et võib-olla oskate soovitada selle esinemise võimalikke põhjuseid. Võib-olla ilmneb viga alles pärast seda, kui puutute kokku teatud sündmusega, või võib-olla juhtub see ainult mobiilis.

Samuti ei tee kahju koodibaasi uurimine ja võib-olla probleemi põhjustaja tuvastamine. Seejärel suletakse teie probleem palju kiiremini ja teid määratakse tõenäoliselt seotud teemasse PR.

Suhtlemine klientidega

Võite töötada üksi vabakutselisena või olla väikese meeskonna juhtiv arendaja. Mõlemal juhul oletame, et vastutate projekti raames klientidega suhtlemise eest. 

Nüüd on programmeerija stereotüüp, et me oleme kehvad suhtlejad. Oleme teadaolevalt kasutanud liiga tehnilist kõnepruuki, öelnud teistele, mis on ja mis ei ole võimalik, ning asume isegi kaitsma, kui keegi seab meie lähenemisviisi kahtluse alla.

Niisiis, kuidas me seda stereotüüpi leevendame? Küsige klientidelt, mida nad tahavad, ja kuulake alati nende tagasisidet. Siin on, kuidas seda teha.

Küsige õigeid küsimusi

Alustuseks veenduge, et teie ja klient olete samal lehel:

• Kes on teie sihtrühm?
• Mis on saidi eesmärk?
• Kes on teie lähim konkurent ja mida nad õigesti teevad?

Küsimuste esitamine on ka hea viis positiivselt kirjutada, eriti olukordades, kus te ei nõustu kliendi tagasiside või otsusega. Küsimuste esitamine sunnib seda inimest oma väiteid toetama, mitte ei ründa teda oma seisukohta kaitstes:

• Kas olete sellega nõus, isegi kui sellega kaasneb täiendav jõudluskulu?
• Kas komponendi liigutamine aitab meil oma eesmärki paremini täita?
• Suurepärane, kes vastutab selle hooldamise eest pärast käivitamist? 
• Kas teate kohe, kas nende kahe värvi kontrastsus ületab WCAG AA standardid?

Küsimused on palju süütumad ja tõstavad uudishimu vaenu üle.

Müü ise

Kui räägite potentsiaalsele kliendile, peate veenma teda teid palkama. Miks peaks klient just sind valima? Oluline on täpsustada järgmist:

• Kes sa oled
• Mida sa teed
• Miks sa sobid sellele tööle
• Lingid teie tehtud asjakohastele töödele

Ja kui olete töökoha saanud ja peate lepingu sõlmima, pidage meeles, et pole hirmutavamat sisu kui hulk seadusi. Kuigi see on kirjutatud disainiprojektide jaoks, Lepinguline tapja võib olla hea lähtepunkt millegi palju sõbralikuma kirjutamiseks.

Teie tähelepanu detailidele võib olla erinevus teie ja teise sama projekti võita üritava arendaja vahel. Minu kogemuse kohaselt võtavad kliendid sama hõlpsalt tööle arendaja, kellega nad arvavad, et nendega töötamine neile meeldib, kui see, kes on selle töö jaoks tehniliselt kõige pädevam või kogenum.

Kirjutamise mikrokoopia

Mikrokoopia on kasutajasõbralik kirjutamise kunst UI teateid, nagu vead. Vean kihla, et on olnud aegu, kus teie kui arendaja pidite kirjutama veateateid, kuna need pandi käivitamise ajaks tagapõletisse.

Seetõttu näeme mõnikord selliseid vigu:

Error: Unexpected input (Code 693)

Vead on viimane asi, millega soovite, et teie kasutajad tegeleksid. Kuid neid juhtub ja me ei saa sellega midagi teha. Siin on mõned näpunäited oma mikrokopeerimisoskuste parandamiseks.

Vältige tehnilist kõnepruuki

Enamik inimesi ei tea, mis server on, samas kui 100% programmeerijatest teavad. Seetõttu pole ebatavaline näha veateates ebatavalisi termineid, näiteks API või "ajalõpu täitmine".

Kui teil pole tegemist tehnilise kliendi või kasutajabaasiga, on tõenäoline, et enamik teie kasutajaid ei osalenud arvutiteaduse kursustel ega tea, kuidas Internet töötab ja miks konkreetne asi ei tööta. Seega viga.

Seetõttu ei tohiks hea veateade seletada miks midagi läks valesti, sest selliste selgituste jaoks võib olla vaja kasutada hirmutavaid tehnilisi termineid. Sellepärast on väga oluline vältida tehnilise kõnepruugi kasutamist.

Ärge kunagi süüdistage kasutajat

Kujutage ette: ma proovin teie platvormile sisse logida. Seega avan oma brauseri, külastan teie veebisaiti ja sisestan oma andmed. Siis öeldakse mulle: "Teie e-post/parool on vale."

Kuigi tundub dramaatiline arvata, et see sõnum on vaenulik, paneb see mind alateadlikult tundma end rumalana. Microcopy ütleb, et kasutajat pole kunagi okei süüdistada. Proovige muuta oma sõnum millekski vähem näpuotsaliseks, näiteks see näide, mis on kohandatud Mailchimpi sisselogimisest: „Vabandust, see meili-parooli kombinatsioon pole õige. Aitame teil oma konto taastada."

Tahaksin ka lisada, kui oluline on vältida KÕIKE suurtähtede ja hüüumärkide kasutamist! Muidugi saab neid kasutada põnevuse edastamiseks, kuid mikrokoopias tekitavad need kasutaja suhtes vaenulikkuse tunde.

Ärge koormake kasutajat üle

Huumori kasutamine mikrokoopias on hea mõte! See võib tuju kergendada ja see on lihtne viis ohjeldada isegi kõige hullematest vigadest põhjustatud negatiivsust.

Aga kui te seda ei kasuta suurepäraselt, võib see tunduda kasutajat halvustavalt ja solvavana. See on lihtsalt a suur riski võtta.

Mailchimp ütleb seda hästi:

[D]Ära tee nalja – pealesunnitud huumor võib olla hullem kui üldse mitte. Kui te pole kindel, hoidke sirget nägu.

(Rõhuasetus minu poolt)

Juurdepääsetava märgistuse kirjutamine

Võiksime hõlpsasti kulutada terve artikli juurdepääsetavuse ja selle tehnilise kirjutamisega seotud seoste kohta. Juurdepääsetavus sisaldub sageli sisustiili juhendites, sealhulgas nendes Microsoft ja MailChimp.

Olete arendaja ja ilmselt teate juurdepääsetavuse kohta nii palju. Võite isegi olla üks hoolsamaid arendajaid, kes muudab juurdepääsetavuse teie töövoo keskseks osaks. Sellegipoolest on uskumatu, kui sageli jäetakse juurdepääsetavuse kaalutlused tahaplaanile, hoolimata sellest, kui oluline me kõik teame, et on kättesaadavad võrgukogemused, mis hõlmavad kõiki võimeid.

Seega, kui leiate, et rakendate oma koodi kellegi teise teksti, kirjutate dokumente teistele arendajatele või isegi kirjutate UI kopeerige ennast, pidage meeles mõningaid peamisi juurdepääsetavuse parimaid tavasid, kuna need täiendavad kõiki muid tehnilise kirjutamise nõuandeid.

Asjad nagu:

Andy Bell pakub mõnda suhteliselt väikesed asjad, mida saate teha, et muuta sisu kättesaadavamaks, ja tasub nende kontrollimiseks aega kulutada. Ja lihtsalt löökide jaoks, John Rhea näitab mõningaid korralikke toimetamisnippe mis on võimalikud, kui töötame semantiliste HTML-elementidega.

Järeldus

Need olid kuus viisi, mis näitavad, kuidas tehniline kirjutamine ja arendus langevad kokku. Kuigi näited ja nõuanded ei pruugi olla raketiteadus, loodan, et leidsite neist kasu, olgu selleks siis koostöö teiste arendajatega, oma töö hooldamine, näpuotsaga oma eksemplari kirjutamine või isegi projektiettepaneku koostamine. asju.

Lõpptulemus: oma kirjutamisoskuste teravdamine ja kirjutamisega veidi lisapingutuste tegemine võib tegelikult muuta teid paremaks arendajaks.

Tehnilised kirjutamisvahendid

Kui olete huvitatud tehnilisest kirjutamisest:

Kui olete huvitatud copywritingust:

Kui olete huvitatud mikrokoopiast:

Kui olete huvitatud professionaalse stiilijuhi kasutamisest oma kirjutamise parandamiseks:

Kui olete huvitatud juurdepääsetavuse huvides kirjutamisest: