Tekninen kirjoittaminen kehittäjille

HTML, CSS, JavaScript, Python, PHP, C++, Dart – ohjelmointikieliä on niin monia, ja saatat olla jopa täysin sujuva useissa niistä! Mutta kun pyrimme kirjoittamaan enemmän ja parempaa koodia, tavasta kirjoittaa ja kommunikoida jokapäiväisellä kielellä tulee yhä tärkeämmäksi… ja ehkä jopa unohdettu.

Tapa, jolla kirjoitamme koodista ja sen ympärillä, on kiistatta yhtä tärkeä kuin itse koodi. Ja huolimatta siitä, missä olet tällä linjalla, voimme kaikki olla yhtä mieltä siitä, että sanamme voivat sekä auttaa että vahingoittaa koodin tehokkuutta.

Tässä artikkelissa haluan hahmotella, kuinka nämä kaksi näennäisesti erillistä alaa – ohjelmointi ja kirjoittaminen – voivat yhdistyä ja viedä kehittäjätaitomme uudelle tasolle.

Odota, tekninen kirjoitus? Kyllä, juuri sitä tarkoitan. Uskon todella, että olemme kaikki kirjailijoita tavalla tai toisella. Ja olen täällä antaakseni sinulle kirjoitusvinkkejä, neuvoja ja esimerkkejä siitä, kuinka se voi tehdä sinusta sekä paremman kehittäjän että kommunikaattorin.

Tekninen kirjoitus on kaikkialla

Viime vuonna suositun Mac Git -asiakkaan Towerin takana oleva tiimi kyselyyn vastannut yli 4,000 kehittäjää ja havaitsi, että lähes 50 % heistä käytti 3-6 tuntia päivässä koodin kirjoittamiseen.

Ja kyllä, tämä on yksi kysely, joka vastaa melko kapealle ryhmälle, mutta luulen, että monet meistä kuuluvat jonnekin tälle alueelle. Joka tapauksessa kehittäjä ei kirjoita koodia 24/7, koska kuten tämä kysely viittaa, käytämme paljon aikaa muihin asioihin.

Se voi sisältää:

• uuden ominaisuuden esittely,
• dokumentoida tämä uusi ominaisuus,
• uuteen ominaisuuteen liittyvän työlipun päivittäminen tai
• ruuhkatöitä tämän uuden ominaisuuden tukemiseksi.

Tietysti aina on aikaa kylpyhuonetaukoille ja Wordlellekin.

Joka tapauksessa suurin osa asioista, joita teemme, liittyy kommunikointiin ihmisten, kuten tiimisi, kollegoiden, asiakkaiden, käyttäjien ja muiden kehittäjien kanssa.

Joten käytämme suuren osan ajastamme kommunikointiin ihmisten kanssa sanoja tietokoneiden kanssa käytävän viestinnän lisäksi koodi. Sanat ovat kirjoitettua kieltä. Ja jos kirjoittaisimme sanamme paremmin, kommunikoisimme paremmin. Kun kommunikoimme paremmin, saamme todennäköisemmin haluamamme.

Se on Tekninen kirjoitus 101.

Eikä se edes lopu tähän. Jotkut ohjelmoijat haluavat myös tehdä omia tuotteitaan, mikä tarkoittaa, että heidän on tehtävä markkinoinnista osa työtään. Teknisellä kirjoittamisella on myös suuri rooli siinä. Joten kyllä. Mielestäni on melko reilua sanoa, että tekninen kirjoittaminen on todellakin joka paikassa.

Mikä on hyvä kielioppi?

Koska ohjelmointikieliä on niin monia, viimeinen asia, jonka haluamme, on oppia toinen.

Kielioppi on olennainen osa englantia, ja se vapauttaa viestinnän täyden potentiaalin. Se tekee meistä muodollisempia, ammattimaisempia ja johdonmukaisempia.

Annan sinulle nopean yhteenvedon kielestä.

Englannin syntaksi

Kuten ohjelmointikielillä, englannin syntaksi on hyvin määritelty, ja se alkaa sanoilla.

Sanat ovat englannin rakennuspalikoita, ja ne jakautuvat kahdeksaan ämpäriin:

Ajattele näitä kuten UI komponentit: ne ovat modulaarisia kappaleita, joita liikuttamalla voit muodostaa täydellisen ja vankan lauseen, samalla tavalla kuin kokoat kokonaisen ja vankan lauseen UI. Pitääkö kaikkien komponenttien olla siellä koko ajan? Ainakaan! Kokoa lause kappaleista, joita tarvitset kokemuksen täydentämiseen, aivan kuten käyttäisit käyttöliittymää.

Ääni ja sävy

Sanasto, välimerkit, lauseen rakenne ja sanavalinta. Nämä ovat kaikki englannin kielen ainesosia. Käytämme niitä ideoiden jakamiseen, kommunikointiin ystävien ja perheen kanssa sekä sähköpostien lähettämiseen työtovereillemme.

Mutta on tärkeää ottaa huomioon kuulostaa viesteistämme. On hämmästyttävää, kuinka yksi huutomerkki voi muuttaa viestin sävyn kokonaan:

1. Pidän ohjelmoinnista.
2. I pitää ohjelmointi! :)

Ääni on helppo sekoittaa sävyyn ja päinvastoin.

Ääni Tämä koskee sanavalintaamme, joka riippuu kontekstista. Esimerkiksi aloittelijoille suunnatussa opetusohjelmassa käytetään todennäköisemmin slangia ja epävirallista kieltä välittääkseen ystävällisen äänen, kun taas asiakirjat voidaan kirjoittaa muodollisesti, vakavasti ja ammattimaisesti, jotta päästään suoraan asiaan.

Sama viesti kahdella eri äänellä kirjoitettuna:

• Fun: "Laajenna sosiaalista verkostoasi ja pysy ajan tasalla trendikkäistä asioista."
• Vakava: "Etsi työpaikkoja yhdeltä suurimmista sosiaalisen verkostoitumisen sovelluksista ja online-työmarkkinoilta."

Ei ole epätavallista kirjoittaa vahingossa viestejä, jotka tulevat alentuneiksi, loukkaaviksi ja epäammattimaisiksi. Tämä on paikka sävy tulee pelata. Lue viestisi ääneen, pyydä muita lukemaan ne puolestasi ja kokeile välimerkkejäsi ja lauserakennettasi. Näin sävelät sävyäsi.

Tässä on toinen tapa ajatella asiaa: äänesi ei koskaan muutu, mutta sävysi muuttuu. Äänesi muistuttaa sitä, kuka olet ihmisenä, kun taas sävy on, kuinka reagoit tietyssä tilanteessa.

Aktiivinen ja passiivinen ääni

Lause sisältää aina näyttelijän, verbin ja kohteen. Järjestys, jossa nämä tulevat, määrittää, onko lause kirjoitettu aktiivisella vai passiivisella äänellä.

Näyttelijä tulee ensimmäiseksi aktiivinen ääni. Esimerkki: "CSS maalaa taustan."

Aktiivista ääntä käyttävät lauseet ovat suoraviivaisempia kuin niiden vastineet. Ne ovat selkeämpiä, lyhyempiä ja ymmärrettävämpiä – täydelliset ammattimaisempaan ääneen, joka menee suoraan asiaan.

Kanssa passiivinen ääni, näyttelijä on viimeinen. (Katso mitä tein siellä?) Tämä tarkoittaa, että näyttelijämme - tässä tapauksessa CSS - tulee lopussa näin: "Tausta on maalattu CSS:llä."

Lukijat muuttavat yleensä passiivisen äänen päässään aktiiviseksi ääneksi, mikä lisää käsittelyaikaa. Jos olet koskaan kuullut, että aktiivisella äänellä kirjoittaminen on parempi, tämä on yleensä syy siihen. Tekniset kirjoittajat suosivat aktiivista ääntä suurimman osan ajasta, lukuun ottamatta hyvin harvoja poikkeuksia, kuten tutkimukseen viitaten: "On ehdotettu, että…"

Mutta se ei tarkoita, että sinun pitäisi aina pyrkiä aktiiviseen ääneen. Vaihtaminen yhdestä toiseen - jopa samassa kappaleessa - voi saada sisältösi kulkemaan saumattomasti lauseesta toiseen, jos sitä käytetään tehokkaasti.

Virheiden välttäminen

Kielioppi on kyse kielen rakenteesta ja oikeellisuudesta, eikä siinä ole mitään parempaa kuin dokumentin nopea oikolukeminen. On erittäin tärkeää poistaa kirjoituksistasi kirjoitusvirheet, kielioppiongelmat ja semanttiset puutteet.

Tämän artikkelin lopussa näytän sinulle korvaamattomat työkalut, joita ammattilaiset käyttävät välttääkseen kirjoitusvirheet. On selvää, että nykyään lähes kaikessa on sisäänrakennetut oikoluku; koodieditoreissamme on jopa oikeinkirjoituksen tarkistus- ja linting-laajennuksia, jotka auttavat estämään virheitä. 

Mutta jos etsit yhden luukun työkalua kaiken kielioppiin, Grammarly on yksi yleisimmin käytetyistä työkaluista. En saa siitä takaiskua tai mitään. Se on vain todella hieno työkalu, jota monet toimittajat ja kirjoittajat käyttävät puhtaan ja selkeän sisällön kirjoittamiseen – samalla tavalla kuin käytät Emmetiä, eslinttiä tai mitä tahansa muuta linteriä puhtaan ja selkeän koodin kirjoittamiseen.

Koodikommenttien kirjoittaminen

Asioilla, joita kirjoitamme muille kehittäjille, voi olla suuri vaikutus työmme yleiseen laatuun, olipa kyse sitten siitä, mitä kirjoitamme koodiin, miten selitämme koodin tai kuinka annamme palautetta koodinpalasta.

On mielenkiintoista, että jokaisella ohjelmointikielellä on vakioominaisuudet kommentin kirjoittamista varten. Heidän tulee selittää, mitä koodi tekee. Tällä en tarkoita tällaisia ​​epämääräisiä kommentteja:

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

Käytä sen sijaan kommentteja, jotka tarjoavat lisätietoja:

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

Kaikki on kiinni kontekstista. "Millaista ohjelmaa rakennan?" on juuri sellainen kysymys, jonka sinun pitäisi kysyä itseltäsi.

Kommenttien pitäisi lisätä arvoa

Ennen kuin tarkastelemme, mikä tekee "hyvästä" koodikommentista, tässä on kaksi esimerkkiä laiskoista kommenteista:

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

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

Muista, että kommentin tarkoitus on lisätä koodinpätkälle arvoa, ei toistaa sitä. Jos et voi tehdä sitä, sinun on parempi jättää koodi ennalleen. Mikä tekee näistä esimerkeistä "laiskaksi", on se, että ne vain toistavat sen, mitä koodi ilmeisesti tekee. Tässä tapauksessa kommentit ovat tarpeettomia, koska ne kertovat meille sen, minkä jo tiedämme – ne eivät tuota lisäarvoa!

Kommenttien tulee vastata nykyistä koodia

Vanhentuneet kommentit eivät ole harvinainen näky suurissa projekteissa; uskallan sanoa eniten hankkeisiin.

Kuvitellaanpa David, ohjelmoija ja kaikin puolin siisti kaveri, jonka kanssa viettää aikaa. David haluaa lajitella merkkijonoluettelon aakkosjärjestyksessä A:sta Z:hen, joten hän tekee selvän JavaScriptin:

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

Sitten David tajuaa, että sortWords() todella lajittelee luettelot Z:sta A:han. Se ei ole ongelma, sillä hän voi yksinkertaisesti kääntää tulosteen:

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

Valitettavasti David ei päivittänyt koodikommenttiaan.

Kuvittele nyt, että en kertonut sinulle tätä tarinaa ja että näit vain yllä olevan koodin. Luulisi luonnollisesti, että toisen koodirivin suorittamisen jälkeen "kaupungit" lajitellaan Z:sta A:han! Tämä koko hämmennysfiasko johtui vanhentuneesta kommentista.

Vaikka tämä saattaa olla liioiteltu esimerkki, jotain vastaavaa voi (ja usein tapahtuu) tapahtua, jos kilpailet lähellä olevaa määräaikaa vastaan. Onneksi tämä voidaan estää noudattamalla yhtä yksinkertaista sääntöä… muuta kommenttejasi samalla kun vaihdat koodia.

Tämä on yksi yksinkertainen sääntö, joka säästää sinut ja tiimisi monelta tekninen velka.

Nyt kun tiedämme, miltä huonosti kirjoitetut kommentit näyttävät, katsotaanpa joitain hyviä esimerkkejä.

Kommenttien tulee selittää unidiomaattinen koodi

Joskus, luonnollinen tapa tehdä asioita ei ole oikea. Ohjelmoijat saattavat joutua "rikkomaan" standardeja hieman, mutta kun he tekevät niin, on suositeltavaa jättää pieni kommentti selittääkseen heidän perustelunsa:

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

Se on hyödyllistä, eikö? Jos olit vastuussa tämän koodin tarkistamisesta, sinulla on saattanut olla houkutus korjata se ilman, että kommentti selittää, mitä tapahtuu.

Kommentit voivat tunnistaa tulevat tehtävät

Toinen hyödyllinen asia kommenteissa on myöntää, että tehtävää on enemmän.

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

Tällä tavalla voit keskittyä virtaukseen. Ja myöhemmin sinä (tai joku muu) voit palata korjaamaan sen.

Kommentit voivat linkittää takaisin lähteeseen

Joten löysit juuri ratkaisun ongelmaasi StackOverflowsta. Koodin kopioinnin ja liittämisen jälkeen on joskus hyvä säilyttää linkki vastaukseen, joka auttoi sinua, jotta voit palata siihen myöhempää tarvetta varten.

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

Tämä on tärkeää, koska ratkaisut voivat muuttua. On aina hyvä tietää, mistä koodisi on peräisin siltä varalta, että se joskus hajoaa.

Vetopyyntöjen kirjoittaminen

Vetopyynnöt (PRs) ovat olennainen osa minkä tahansa hankkeen. Ne ovat koodiarvioiden ytimessä. Ja koodin tarkistuksista voi nopeasti muodostua pullonkaula tiimisi suorituskyvyssä ilman hyvää sanamuotoa.

Hyvä PR kuvaus tiivistää mitä muutosta tehdään ja miksi sitä tehdään. Suurissa projekteissa on vetopyyntömalli, kuten tämä, joka on mukautettu a todellinen esimerkki:

## 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ältä epämääräistä PR otsikot

Vältä otsikoita, jotka näyttävät tältä:

• Korjaa rakenne.
• Korjaa vika.
• Lisää laastari.

Nämä eivät edes yritys kuvailemaan, minkä rakenteen, bugin tai korjaustiedoston kanssa olemme tekemisissä. Pieni lisätieto siitä, mikä osa rakennuksesta on korjattu, mikä bugi korjattiin tai mikä korjaustiedosto lisättiin, voi auttaa parantamaan viestintää ja yhteistyötä kollegojesi kanssa. Se tasoittaa ja saa ihmiset samalle sivulle.

PR otsikot kirjoitetaan perinteisesti pakottava jännitys. Ne ovat yksirivinen yhteenveto kaikesta PR, ja heidän pitäisi kuvata mitä on tekemässä PR.

Tässä muutamia hyviä esimerkkejä:

• Tukee mukautettuja srcset-attribuutteja NgOptimizedImagessa
• Kuvan oletusasetus on 75 % kuvanlaadusta
• Lisää eksplisiittiset valitsimet kaikille sisäänrakennetuille ControlValueAccessoreille

Vältä pitkiä PRs

Suuri PR tarkoittaa valtavaa kuvausta, eikä kukaan halua tarkistaa satoja tai tuhansia koodirivejä, joskus vain hylätäkseen koko asian!

Sen sijaan voit:

• kommunikoi tiimisi kanssa Kysymykset,
• tehdä suunnitelma,
• pilkko ongelma pienempiin osiin tai
• työstää jokaista kappaletta erikseen omalla PR.

Eikö se ole nyt paljon siistimpää?

Anna tiedot kohdassa PR elin

Toisin kuin PR otsikko, runko on Ishayoiden opettaman paikka kaikille yksityiskohdille, mukaan lukien:

• Miksi PR tehdään?
• Miksi tämä on paras lähestymistapa?
• Lähestymistavan mahdolliset puutteet ja ideat niiden ratkaisemiseksi, jos mahdollista
• Virhe tai lipun numero, vertailutulokset jne.

Virheistä ilmoittaminen

Virheraportit ovat yksi projektin tärkeimmistä osista. Ja kaikki hienot projektit perustuvat käyttäjien palautteeseen. Yleensä jopa lukemattomien testien jälkeen käyttäjät löytävät useimmat viat. Käyttäjät ovat myös suuria idealisteja, ja joskus heillä on ominaisuusideoita; kuuntele niitä!

Teknisissä projekteissa kaikki tämä tehdään raportoimalla ongelmista. Hyvin kirjoitettu ongelma toisen kehittäjän on helppo löytää ja vastata siihen.

Esimerkiksi useimmat suuret projektit tulevat mukana 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.

Kerää kuvakaappauksia

Tallenna ongelma käyttämällä järjestelmän näyttökuvausapuohjelma.

Jos se on kuvakaappaus a CLI ohjelma, varmista, että teksti on selkeää. Jos se on a UI ohjelma, varmista, että kuvakaappaus kaappaa oikeat elementit ja tilat.

Sinun on ehkä kuvattava todellinen vuorovaikutus ongelman osoittamiseksi. Jos näin on, yritä tallentaa GIF-tiedostoja näytön tallennustyökalulla.

Kuinka toistaa ongelma

Ohjelmoijien on paljon helpompaa ratkaista virhe, kun se on livenä heidän tietokoneessaan. Siksi hyvän sitoumuksen tulee sisältää vaiheet, joilla ongelma toistetaan tarkasti.

Tässä esimerkki:

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.

Ehdota syytä

Sinä sait vian kiinni, joten voit ehkä ehdottaa mahdollisia syitä siihen, miksi se on olemassa. Ehkä vika ilmenee vasta sen jälkeen, kun kohtaat tietyn tapahtuman, tai ehkä se tapahtuu vain mobiililaitteella.

Ei myöskään haittaa koodikannan tutkimista ja ehkä ongelman aiheuttajan tunnistamista. Sitten ongelmasi suljetaan paljon nopeammin ja sinut todennäköisesti ohjataan asiaan liittyvään PR.

Viestintä asiakkaiden kanssa

Saatat työskennellä yksin freelancerina tai ehkä olet pääkehittäjä pienessä tiimissä. Kummassakin tapauksessa oletetaan, että olet vastuussa vuorovaikutuksesta projektin asiakkaiden kanssa. 

Ohjelmoijan stereotypia on, että olemme huonoja kommunikoijia. Meidän on tiedetty käyttävän liian teknistä ammattikieltä, kertovan muille, mikä on ja mikä ei ole mahdollista, ja jopa puolustautuvan, kun joku kyseenalaistaa lähestymistapamme.

Joten, miten voimme lieventää tätä stereotypiaa? Kysy asiakkailta, mitä he haluavat, ja kuuntele aina heidän palautetta. Näin voit tehdä sen.

Kysy oikeat kysymykset

Aloita varmistamalla, että sinä ja asiakas olette samalla sivulla:

• Kuka on kohdeyleisösi?
• Mikä on sivuston tavoite?
• Kuka on lähin kilpailijasi ja mitä he tekevät oikein?

Kysymysten esittäminen on myös hyvä tapa kirjoittaa positiivisesti, varsinkin tilanteissa, joissa olet eri mieltä asiakkaan palautteen tai päätöksen kanssa. Kysymysten esittäminen pakottaa henkilön tukemaan omia väitteitään sen sijaan, että hyökkäät häntä vastaan ​​puolustamalla omaa kantaasi:

• Hyväksytkö sen, vaikka siihen sisältyy ylimääräisiä suorituskustannuksia?
• Auttaako komponentin siirtäminen meitä saavuttamaan tavoitteemme paremmin?
• Hienoa, kuka on vastuussa sen ylläpitämisestä käynnistämisen jälkeen? 
• Tiedätkö suoraan, ylittääkö näiden kahden värin kontrasti WCAG AA -standardit?

Kysymykset ovat paljon viattomampia ja edistävät uteliaisuutta vihamielisyyden sijaan.

Myy itsesi

Jos teet puheenvuoron mahdolliselle asiakkaalle, sinun on saatava hänet palkkaamaan sinut. Miksi asiakkaan pitäisi valita sinut? On tärkeää määrittää seuraavat asiat:

• Kuka sinä olet
• Mitä teet
• Miksi olet hyvä työhön
• Linkkejä tekemiisi töihin

Ja kun saat työpaikan ja sinun on tehtävä sopimus, muista, ettei ole olemassa pelottavampaa sisältöä kuin joukko lakia. Vaikka se on kirjoitettu suunnitteluprojekteja varten, Sopimusmurhaaja voi olla hyvä lähtökohta kirjoittaa jotain paljon ystävällisempää.

Yksityiskohtien huomioiminen saattaa olla ero sinun ja toisen saman projektin voittavan yrittäjän välillä. Kokemukseni mukaan asiakkaat palkkaavat yhtä helposti kehittäjän, jonka kanssa he uskovat nauttivansa työskentelystä, kuin sellaisen, joka on teknisesti pätevin tai kokein kyseiseen työhön.

Kirjoittava mikrokopio

Mikrokopio on käyttäjäystävällisen kirjoittamisen taito UI viestejä, kuten virheitä. Lyön vetoa, että on ollut aikoja, jolloin sinun on kehittäjänä täytynyt kirjoittaa virheilmoituksia, koska ne on asetettu takapolttimeen aina käynnistysaikaan asti.

Tästä syystä näemme joskus tämän kaltaisia ​​virheitä:

Error: Unexpected input (Code 693)

Virheet ovat viimeinen asia, jonka haluat käyttäjien käsittelevän. Mutta niitä tapahtuu, emmekä voi asialle mitään. Tässä on muutamia vinkkejä mikrokopiointitaitojen parantamiseen.

Vältä teknistä ammattislangia

Useimmat ihmiset eivät tiedä mitä palvelin on, kun taas 100% ohjelmoijista tietää. Tästä syystä ei ole epätavallista nähdä virheilmoitukseen kirjoitettuja epätavallisia termejä, kuten API tai "aikakatkaisun suoritus".

Ellet ole tekemisissä teknisen asiakkaan tai käyttäjäkunnan kanssa, on todennäköistä, että suurin osa käyttäjistäsi ei käynyt tietojenkäsittelytieteen kurssia eivätkä tiedä, miten Internet toimii ja miksi jokin tietty asia ei toimi. Siksi virhe.

Siksi hyvän virheilmoituksen ei pitäisi selittää miksi jotain meni pieleen, koska sellaiset selitykset saattavat edellyttää pelottavien teknisten termien käyttöä. Siksi on erittäin tärkeää välttää teknisen ammattikieltä.

Älä koskaan syytä käyttäjää

Kuvittele tämä: Yritän kirjautua alustallesi. Joten avaan selaimeni, käyn verkkosivustollasi ja kirjoitan tietoni. Sitten minulle sanotaan: "Sähköpostiosoitteesi/salasanasi on väärä."

Vaikka tuntuu dramaattiselta ajatella, että tämä viesti on vihamielinen, se saa minut alitajuisesti tuntemaan oloni tyhmäksi. Microcopy sanoo, että ei ole koskaan oikein syyttää käyttäjää. Yritä muuttaa viestisi johonkin vähemmän sormella osoittavaan, kuten tämä Mailchimpin kirjautumisesta muokattu esimerkki: "Anteeksi, tuo sähköposti-salasana-yhdistelmä ei ole oikea. Voimme auttaa sinua palauttamaan tilisi."

Haluaisin myös lisätä, että on tärkeää välttää KAIKKIA kirjaimia ja huutomerkkejä! Toki niitä voidaan käyttää välittämään jännitystä, mutta mikrokopiossa ne luovat vihamielisyyden tunteen käyttäjää kohtaan.

Älä kuormita käyttäjää

Huumorin käyttäminen mikrokopiossa on hyvä idea! Se voi piristää mielialaa, ja se on helppo tapa hillitä pahimpienkin virheiden aiheuttamaa negatiivisuutta.

Mutta jos et käytä sitä täydellisesti, se voi tuntua alentuvalta ja loukkaavalta käyttäjää kohtaan. Se on vain a suuri ottaa riski.

Mailchimp sanoo sen hyvin:

[D]Älä tee vitsejäsi – pakotettu huumori voi olla pahempaa kuin ei ollenkaan. Jos olet epävarma, pidä kasvot suorana.

(korostus minun)

Kirjoitetaan helppokäyttöisiä merkintöjä

Voisimme helposti käyttää koko artikkelin saavutettavuudesta ja siitä, miten se liittyy tekniseen kirjoittamiseen. Helvetti, saavutettavuus sisältyy usein sisällön tyylioppaisiin, mukaan lukien Microsoft ja MailChimp.

Olet kehittäjä ja tiedät todennäköisesti jo niin paljon saavutettavuudesta. Saatat jopa olla yksi ahkereimmista kehittäjistä, joka tekee esteettömästä työnkulkusi keskeisen osan. Silti on uskomatonta, kuinka usein esteettömyysnäkökohdat jäävät taka-alalle, vaikka me kaikki tiedämme kuinka tärkeää on tehdä helppokäyttöisistä verkkokokemuksista, jotka sisältävät kaikki kyvyt.

Joten jos huomaat ottavan koodiisi jonkun muun tekstinkirjoituksen, kirjoittavan dokumentteja muille kehittäjille tai jopa kirjoittavan UI kopioi itsesi, muista joitakin perustavanlaatuisia saavutettavuuden parhaita käytäntöjä, sillä ne täydentävät kaikki muut teknisen kirjoittamisen neuvot.

Asioita kuten:

Andy Bell tarjoaa joitain suhteellisen pieniä asioita, joita voit tehdä sisällön saatavuuden parantamiseksi, ja niiden tarkistamiseen kannattaa käyttää aikaa. Ja vain potkuja varten, John Rhea esittelee hienoja editointitemppuja jotka ovat mahdollisia, kun työskentelemme semanttisten HTML-elementtien kanssa.

Yhteenveto

Nämä olivat kuusi tapaa, jotka osoittavat, kuinka tekninen kirjoittaminen ja kehitys sopivat yhteen. Vaikka esimerkit ja neuvot eivät ehkä ole rakettitiedettä, toivon, että pidit niistä hyödyllisiä, olipa kyse sitten yhteistyöstä muiden kehittäjien kanssa, oman työn ylläpitämisestä, oman kopion kirjoittamisesta hyppysellä tai jopa projektiehdotuksen laatimisesta. asioita.

Tärkeintä: kirjoitustaitosi terävöittäminen ja hieman ylimääräisen vaivannäön lisääminen kirjoittamiseen voivat itse asiassa tehdä sinusta paremman kehittäjän.

Tekniset kirjoitusresurssit

Jos olet kiinnostunut teknisestä kirjoittamisesta:

Jos olet kiinnostunut tekstinkirjoittamisesta:

Jos olet kiinnostunut mikrokopiosta:

Jos olet kiinnostunut ammattimaisen tyylioppaan käyttämisestä kirjoittamisen parantamiseen:

Jos olet kiinnostunut kirjoittamaan esteettömyydestä: