Technikai írás fejlesztőknek

HTML, CSS, JavaScript, Python, PHP, C++, Dart – rengeteg programozási nyelv létezik, és lehet, hogy ezek közül többet teljesen folyékonyan beszélsz! De ahogy arra törekszünk, hogy több és jobb kódot írjunk, az a mód, ahogyan a mindennapi nyelven írunk és kommunikálunk, egyre fontosabbá válik… és talán figyelmen kívül hagyjuk.

Az, ahogyan a kódról és a kód körül írunk, vitathatatlanul ugyanolyan fontos, mint maga a kód. És annak ellenére, hogy hol esik ezen a vonalon, mindannyian egyetértünk abban, hogy szavaink segíthetik és rontják a kód hatékonyságát.

Ebben a cikkben azt szeretném felvázolni, hogy ez a két, látszólag különálló terület – a programozás és az írás – hogyan jöhet létre, és hogyan emelheti fejlesztői készségeinket a következő szintre.

Várj, műszaki írás? Igen, pontosan erre gondolok. Őszintén hiszem, hogy ilyen vagy olyan értelemben mindannyian írók vagyunk. És azért vagyok itt, hogy írási tippeket, tanácsokat és példákat adjunk Önnek arról, hogyan teheti Önt jobb fejlesztővé és kommunikálóvá.

A műszaki írás mindenhol megtalálható

Tavaly a népszerű Mac Git kliens, a Tower mögött álló csapat több mint 4,000 fejlesztőt kérdeztek meg és azt találta, hogy közel 50%-uk napi 3-6 órát töltött kódírással.

És igen, ez egy olyan felmérés, amely egy meglehetősen szűk csoportot kérdezett meg, de úgy gondolom, hogy sokan közülünk ebbe a tartományba esnek. Bárhogy is legyen, egy fejlesztő nem ír kódot a hét minden napján, 24 órában, mert ahogy ez a szavazás is sugallja, rengeteg időt töltünk más dolgokkal.

Ez magában foglalhatja:

• új funkció bemutatása,
• az új funkció dokumentálása,
• az adott új funkcióhoz kapcsolódó munkajegy frissítése, vagy
• lemaradási munka az új funkció támogatása érdekében.

Természetesen mindig jut idő a fürdőszobai szünetekre és a Wordle-re is.

Mindenesetre a legtöbb dolog, amit általában csinálunk, az olyan emberekkel való kommunikációból áll, mint a csapat, a kollégák, az ügyfelek, a felhasználók és más fejlesztők.

Tehát időnk jó részét az emberekkel való kommunikációval töltjük szavak a számítógépekkel való kommunikáción kívül kód. A szavak írott nyelv. És ha jobban írnánk a szavainkat, jobban kommunikálnánk. Ha jobban kommunikálunk, nagyobb valószínűséggel kapjuk meg, amit akarunk.

Ez a Technical Writing 101.

És itt még nincs vége.. Egyes programozók szívesen készítik saját termékeiket, ami azt jelenti, hogy a marketinget a munkájuk részévé kell tenni. Ebben nagy szerepe van a technikai írásnak is. Szóval igen. Szerintem elég jogos kijelenteni, hogy a technikai írás az valóban mindenhol.

Mi a jó nyelvtan?

Mivel rengeteg programozási nyelv létezik, az utolsó dolog, amit szeretnénk, az, hogy megtanuljunk egy másikat.

Nyelvtan az angol nyelv szerves része, és felszabadítja a kommunikációban rejlő lehetőségeket. Ez formálisabbá, professzionálisabbá és koherensebbé tesz bennünket.

Hadd adjak egy gyors összefoglalót a nyelvről.

Az angol szintaxis

Csakúgy, mint a programozási nyelveknek, az angolnak is jól definiált szintaxisa van, és szavakkal kezdődik.

A szavak az angol építőkövei, és nyolc vödörbe esnek:

Gondolj ilyenekre UI komponensek: moduláris darabok, amelyek mozgatásával teljes és robusztus mondatot alkothat, ugyanúgy, ahogyan egy teljes és robusztus mondatot összeállíthat. UI. Minden alkatrésznek állandóan ott kell lennie? Biztosan nem! Állítson össze egy mondatot azokkal a darabokkal, amelyekre szüksége van az élmény teljessé tételéhez, ugyanúgy, mint egy felülettel.

Hang és hangszín

Szókincs, írásjelek, mondatszerkezet és szóválasztás. Ezek mind az angol nyelv összetevői. Használjuk őket ötletek megosztására, barátainkkal és családtagjainkkal való kommunikációra, valamint e-mailek küldésére munkatársainknak.

De nagyon fontos figyelembe venni a hang üzeneteink közül. Elképesztő, hogy egy felkiáltójel mennyire képes teljesen megváltoztatni az üzenet hangját:

1. Szeretek programozni.
2. I mint programozás! :)

Könnyű összekeverni a hangot a hangszínnel, és fordítva.

Hang ez vonatkozik a szóválasztásunkra, ami a kontextustól függ. Például egy kezdőknek szóló oktatóanyag nagyobb valószínűséggel használja a szlenget és az informális nyelvezetet a barátságos hang közvetítésére, míg a dokumentáció formálisan, komolyan és professzionálisan írható, hogy egyenesen a lényegre térjen.

Ugyanaz az üzenet, két különböző hangon írva:

• Fun: „Bővítse ki közösségi hálózatát, és maradjon naprakész az aktuális trendekről.”
• Komoly: „Találjon állást az egyik legnagyobb közösségi hálózati alkalmazáson és online álláspiacon.”

Nem szokatlan, hogy véletlenül lekezelőnek, sértőnek és szakszerűtlennek tűnő üzeneteket írunk. Ez az, ahol tónus jön a játék. Olvassa el hangosan üzeneteit, kérjen meg másokat, hogy olvassák el helyette, és kísérletezzen az írásjelekkel és a mondatszerkezettel. Így csiszolod a hangnemedet.

Íme egy másik módja ennek: a hangod soha nem változik, de a hangszíned igen. A hangod hasonlít ahhoz, hogy ki vagy, míg a hangszín az, hogy egy adott helyzetben hogyan reagálsz.

Aktív és passzív hang

Egy mondat mindig tartalmaz egy szereplőt, egy igét és egy célpontot. Ezek sorrendje határozza meg, hogy a mondat aktív vagy passzív hangon íródott-e.

A színész az első helyen áll egy aktiv hang. Például: „A CSS kifesti a hátteret.”

Az aktív hangot használó mondatok egyszerűbbek, mint társaik. Tisztábbak, rövidebbek és érthetőbbek – tökéletesek egy professzionálisabb hanghoz, amely egyenesen a lényegre tér.

Egy szenvedő szerkezet, a színész az utolsó. (Lásd, mit csináltam ott?) Ez azt jelenti, hogy a színészünk – jelen esetben a CSS – így jön a végére: „A hátteret CSS festette.”

Az olvasók általában a passzív hangot aktív hanggá alakítják a fejükben, ami több feldolgozási időt eredményez. Ha valaha is hallottad, hogy jobb aktív hangon írni, általában ez az oka. A műszaki írók az idő nagy részében az aktív hangot részesítik előnyben, néhány kivételtől eltekintve, például a kutatásokra hivatkozva: „Azt javasolták, hogy…”

De ez nem jelenti azt, hogy mindig törekednie kell az aktív hangra. Ha az egyikről a másikra vált – akár ugyanabban a bekezdésben is – zökkenőmentesebben áramolhat a tartalom egyik mondatból a másikba, ha hatékonyan használják.

A hibák elkerülése

A nyelvtan a nyelv szerkezetéről és helyességéről szól, és ezt semmivel sem lehet jobban elérni, mint a dokumentum gyors lektorálásával. Nagyon fontos, hogy írásait megszabadítsa a helyesírási hibáktól, a nyelvtani problémáktól és a szemantikai hibáktól.

A cikk végén megmutatom, milyen felbecsülhetetlen értékű eszközöket használnak a szakemberek, hogy elkerüljék az írási hibákat. Nyilvánvaló, hogy manapság szinte mindenbe vannak beépített helyesírás-ellenőrzők; kódszerkesztőink még helyesírás-ellenőrző és szúrós beépülő modulokkal is rendelkeznek a hibák elkerülése érdekében. 

De ha egyablakos eszközt keres a mindenre kiterjedő nyelvtanhoz, Grammarly az egyik legszélesebb körben használt eszköz. Nem kapok visszarúgást ezért vagy ilyesmiért. Ez egy igazán nagyszerű eszköz, amelyet sok szerkesztő és író használ tiszta és tiszta tartalom írásához – hasonlóan ahhoz, ahogyan az Emmet, az eslint vagy bármely más linter segítségével tiszta és világos kódot írhat.

Kód megjegyzések írása

A más fejlesztőknek írt dolgok nagy hatással lehetnek munkánk általános minőségére, legyen szó arról, hogy mit írunk a kódba, hogyan magyarázzuk el a kódot, vagy hogyan adunk visszajelzést egy kódrészletről.

Érdekes, hogy minden programozási nyelv szabványos funkciókkal rendelkezik a megjegyzések írásához. El kell magyarázniuk, mit csinál a kód. Ezzel nem az ehhez hasonló homályos megjegyzésekre gondolok:

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

Ehelyett használjon több információt nyújtó megjegyzéseket:

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

Minden a kontextuson múlik. – Milyen programot építek? pontosan olyan kérdést kell feltenned magadnak.

A megjegyzéseknek értéket kell adniuk

Mielőtt megvizsgálnánk, mitől lesz „jó” egy kód megjegyzés, íme két példa a lusta megjegyzésekre:

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

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

Ne feledje, hogy a megjegyzés célja, hogy értéket adjon egy kódrészlethez, nem pedig megismételni. Ha ezt nem tudja megtenni, jobb, ha a kódot a jelenlegi állapotában hagyja. Ami ezeket a példákat „lustává” teszi, az az, hogy csupán megismétlik azt, amit a kód nyilvánvalóan csinál. Ebben az esetben a megjegyzések feleslegesek, mert azt mondják el, amit már tudunk – nem adnak hozzáadott értéket!

A megjegyzéseknek tükrözniük kell az aktuális kódot

Az elavult megjegyzések nem ritkák a nagy projektekben; be merem mondani a legtöbb projekteket.

Képzeljük el Davidet, egy programozót, és egy nagyon menő srácot, akivel együtt lóghat. David szeretné rendezni a karakterláncok listáját A-tól Z-ig ábécé szerint, ezért megteszi a nyilvánvalót JavaScriptben:

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

David ekkor rájön, hogy a sortWords() valójában Z-től A-ig rendezi a listákat. Ez nem probléma, mivel egyszerűen megfordíthatja a kimenetet:

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

Sajnos David nem frissítette a kód megjegyzését.

Most képzeld el, hogy nem én mondtam el neked ezt a történetet, és csak a fenti kódot láttad. Természetesen azt gondolná, hogy a második kódsor futtatása után a "városok" Z-től A-ig lesznek rendezve! Ezt az egész zavaros fiaskót egy elavult megjegyzés okozta.

Bár ez eltúlzott példa, valami hasonló megtörténhet (és gyakran meg is történik), ha közeli határidővel versenyez. Szerencsére ez egy egyszerű szabály betartásával megelőzhető… a kód megváltoztatásával egyidejűleg módosíthatja megjegyzéseit.

Ez egy egyszerű szabály, amely sok mindentől megkíméli Önt és csapatát technikai adósság.

Most, hogy tudjuk, hogyan néznek ki a rosszul megírt megjegyzések, nézzünk néhány jó példát.

A megjegyzéseknek meg kell magyarázniuk az unidiomatikus kódot

Néha a természetes a dolgok módja nem megfelelő. Előfordulhat, hogy a programozóknak egy kicsit „meg kell törniük” a szabványokat, de ha megteszik, tanácsos hagyni egy kis megjegyzést, amely elmagyarázza az indokaikat:

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

Ez hasznos, igaz? Ha Ön volt a felelős a kód áttekintéséért, akkor kísértést érezhetett, hogy kijavítsa anélkül, hogy a megjegyzés elmagyarázná, mi a helyzet.

A megjegyzések azonosíthatják a jövőbeni feladatokat

Egy másik hasznos dolog a megjegyzésekkel kapcsolatban az, hogy elismerjük, hogy van még tennivaló.

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

Így az áramlásra koncentrálhat. És egy későbbi időpontban Ön (vagy valaki más) visszatérhet és megjavíthatja.

A megjegyzésekben vissza lehet hivatkozni a forrásra

Tehát most talált megoldást problémájára a StackOverflow-n. A kód másolása és beillesztése után néha érdemes megtartani egy linket a válaszhoz, amely segített a megoldásban, hogy később visszatérhessen hozzá.

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

Ez azért fontos, mert a megoldások változhatnak. Mindig jó tudni, honnan származik a kód, arra az esetre, ha elromolna.

Lehívási kérelmek írása

Hívási kérelmek (PRs) minden projekt alapvető eleme. Ők állnak a kódellenőrzés középpontjában. A kódellenőrzések pedig gyorsan szűk keresztmetszetekké válhatnak a csapat teljesítményében megfelelő megfogalmazás nélkül.

Egy jó PR leírása összefoglalja mit változás történik és miért készül. A nagy projektek lekérési kérési sablonnal rendelkeznek, mint például ez a igazi példa:

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

Kerülje a homályos PR címei

Kérjük, kerülje az ehhez hasonló címeket:

• Fix build.
• Hiba javítása.
• Javítás hozzáadása.

Ezek még csak nem is kísérlet hogy leírjuk, milyen builddel, hibával vagy javítással van dolgunk. Egy kis extra részlet arról, hogy a build mely részét javították ki, melyik hibát törölték ki, vagy milyen javítást adtak hozzá, sokat segíthet a jobb kommunikáció és együttműködés kialakításában a kollégákkal. Szintbeállít, és ugyanarra az oldalra juttatja az embereket.

PR a címeket hagyományosan írják felszólító idejű. Ezek egysoros összefoglalói az egésznek PR, és le kell írniuk mit végzi a PR.

Íme néhány jó példa:

• Az egyéni srcset attribútumok támogatása az NgOptimizedImage programban
• Az alapértelmezett képkonfiguráció 75%-os képminőségre
• Adjon hozzá explicit választókat az összes beépített ControlValueAccessorhoz

Kerülje a hosszú PRs

Egy nagy PR hatalmas leírást jelent, és senki sem akar több száz vagy több ezer sornyi kódot átnézni, néha csak azért, hogy a végén az egészet elutasítsa!

Ehelyett a következőket teheti:

• keresztül kommunikálj a csapatoddal Problémák,
• Készíts egy tervet,
• a problémát kisebb darabokra bontani, ill
• dolgozzon minden egyes darabon külön a sajátjával PR.

Nem sokkal tisztább most?

Adja meg a részleteket a PR test

Ellentétben a PR cím, a test az a hely az összes részlethez, beleértve:

• Miért PR készen lenni?
• Miért ez a legjobb megközelítés?
• A megközelítés esetleges hiányosságai, és lehetőség szerint megoldási ötletek
• A hiba vagy a jegy száma, a benchmark eredmények stb.

Hibák jelentése

A hibajelentések minden projekt egyik legfontosabb szempontja. És minden nagyszerű projekt a felhasználói visszajelzésekre épül. Általában még számtalan teszt után is a felhasználók találják meg a legtöbb hibát. A felhasználók is nagy idealisták, és néha vannak jellemző ötleteik; kérlek hallgasd meg őket!

A műszaki projektek esetében mindezt a problémák jelentésével végzik. Egy jól megírt problémát egy másik fejlesztő könnyen megtalálhat és válaszolhat rá.

Például a legtöbb nagy projekthez tartozik egy sablont:

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

Gyűjts képernyőképeket

Rögzítse a problémát a saját segítségével a rendszer képernyő-felvételi segédprogramja.

Ha ez egy képernyőkép a CLI program, győződjön meg arról, hogy a szöveg világos. Ha ez a UI programot, győződjön meg arról, hogy a képernyőkép a megfelelő elemeket és állapotokat rögzíti.

Előfordulhat, hogy egy tényleges interakciót kell rögzítenie a probléma bemutatásához. Ha ez a helyzet, próbálja meg GIF-eket rögzíthet képernyőrögzítő eszközzel.

Hogyan lehet reprodukálni a problémát

A programozók számára sokkal könnyebb megoldani egy hibát, ha az élőben van a számítógépükön. Éppen ezért a jó elköteleződésnek a probléma pontos reprodukálásához szükséges lépéseket kell tartalmaznia.

Íme egy példa:

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.

Javasoljon okot

Te vagy az, aki elkapta a hibát, szóval talán tud javasolni néhány lehetséges okot, hogy miért van ott. Lehet, hogy a hiba csak egy bizonyos eseménnyel való találkozás után következik be, vagy csak mobilon.

Az sem árthat, ha feltárja a kódbázist, és talán azonosítja, mi okozza a problémát. Ezután a problémát sokkal gyorsabban lezárják, és valószínűleg hozzá lesz rendelve a kapcsolódóhoz PR.

Kommunikáció az ügyfelekkel

Dolgozhat egyéni szabadúszóként, vagy egy kis csapat vezető fejlesztője lehet. Mindkét esetben tegyük fel, hogy Ön felelős az ügyfelekkel való kapcsolattartásért a projekt során. 

Nos, a programozói sztereotípia az, hogy rossz kommunikátorok vagyunk. Köztudott, hogy túlzottan technikai zsargont használunk, elmondjuk másoknak, hogy mi lehetséges és mi nem, és még védekezni is fogunk, ha valaki megkérdőjelezi megközelítésünket.

Szóval, hogyan enyhíthetjük ezt a sztereotípiát? Kérdezd meg az ügyfeleket, hogy mit szeretnének, és mindig hallgasd meg visszajelzéseiket. Íme, hogyan kell ezt megtenni.

Tegye fel a megfelelő kérdéseket

Kezdje azzal, hogy győződjön meg arról, hogy Ön és az ügyfél ugyanazon az oldalon vannak:

• Ki a célközönség?
• Mi az oldal célja?
• Ki a legközelebbi versenytársa, és mit csinálnak jól?

A kérdések feltevése is jó módja a pozitív írásnak, különösen olyan helyzetekben, amikor nem ért egyet az ügyfél visszajelzésével vagy döntésével. A kérdések feltevése arra kényszeríti az illetőt, hogy támogassa saját állításait, ahelyett, hogy saját álláspontja védelmével támadná őket:

• Rendben van ezzel még akkor is, ha további teljesítményköltséggel jár?
• Hozzájárul-e az alkatrész mozgatása célunk jobb megvalósításához?
• Remek, ki a felelős annak karbantartásáért az indítás után? 
• Tudja, hogy a két szín közötti kontraszt meghaladja-e a WCAG AA szabványokat?

A kérdések sokkal ártatlanabbak, és felkeltik a kíváncsiságot az ellenségeskedéssel szemben.

Adja el magát

Ha egy leendő ügyfelet szeretne megszólítani, meg kell győznie őt, hogy alkalmazzák Önt. Miért érdemes téged választania az ügyfélnek? Fontos a következők meghatározása:

• Ki vagy
• Amit csinálsz
• Miért vagy alkalmas erre a munkára
• Linkek az Ön által végzett releváns munkákhoz

És ha egyszer megkapja az állást, és szerződést kell kötnie, ne feledje, hogy nincs félelmetesebb tartalom, mint egy csomó jogi aktus. Annak ellenére, hogy tervezési projektekhez írták, a Szerződéses gyilkos jó kiindulópont lehet valami sokkal barátságosabb íráshoz.

A részletekre való odafigyelés jelentheti a különbséget Ön és egy másik fejlesztő között, aki ugyanazt a projektet próbálja megnyerni. Tapasztalataim szerint az ügyfelek ugyanolyan könnyen felvesznek egy fejlesztőt, akivel úgy gondolják, hogy szívesen dolgoznak együtt, mint azt, aki technikailag a legkompetensebb vagy legtapasztaltabb a munkához.

Írásmikromásolat

Mikrofilmkópia a felhasználóbarát írás művészete UI üzeneteket, például hibákat. Lefogadom, hogy voltak olyan esetek, amikor fejlesztőként hibaüzeneteket kellett írnia, mert azok a háttéríróra kerültek egészen az indításig.

Talán ezért látunk néha ehhez hasonló hibákat:

Error: Unexpected input (Code 693)

A hibák az utolsó dolog, amellyel a felhasználók foglalkozni szeretnének. De előfordulnak, és nem tehetünk ellene. Íme néhány tipp a mikromásolási készségek fejlesztéséhez.

Kerülje a szakzsargont

A legtöbb ember nem tudja, mi az a szerver, míg a programozók 100%-a tudja. Éppen ezért nem szokatlan, ha hibaüzenetben szokatlan kifejezéseket látunk, mint pl API vagy „időtúllépési végrehajtás”.

Hacsak nem műszaki ügyféllel vagy felhasználói bázissal van dolgod, valószínűleg a legtöbb felhasználó nem vett részt számítástechnikai tanfolyamon, és nem tudják, hogyan működik az internet, és miért nem működik egy adott dolog. Ezért a hiba.

Ezért egy jó hibaüzenet nem magyarázza meg miért valami elromlott, mert az ilyen magyarázatokhoz ijesztő szakkifejezések használatára lehet szükség. Éppen ezért nagyon fontos, hogy kerüljük a szakzsargon használatát.

Soha ne hibáztasd a felhasználót

Képzelje el ezt: Megpróbálok bejelentkezni a platformjára. Tehát megnyitom a böngészőt, felkeresem a webhelyét, és megadom az adataimat. Aztán azt mondják: „Az e-mail címed/jelszavad hibás.”

Annak ellenére, hogy drámainak tűnik azt gondolni, hogy ez az üzenet ellenséges, tudat alatt hülyének érzem magam. A Microcopy azt mondja, hogy soha nem szabad a felhasználót hibáztatni. Módosítsa üzenetét valami kevésbé mutatósra, például a Mailchimp bejelentkezési adataiból adaptált példát: „Elnézést, ez az e-mail-jelszó kombináció nem megfelelő. Segítünk a fiók visszaállításában."

Azt is szeretném hozzátenni, hogy kerülni kell a CSUTA NAGYBETŰ és a felkiáltójeleket! Természetesen használhatók az izgalom közvetítésére, de mikromásolásban ellenséges érzést keltenek a felhasználóval szemben.

Ne terhelje túl a felhasználót

A humor használata a mikromásolatban jó ötlet! Feldobhatja a hangulatot, és egyszerű módja annak, hogy megfékezze a legrosszabb hibák okozta negativitást.

De ha nem használod tökéletesen, leereszkedőnek és sértőnek tűnhet a felhasználó számára. Ez csak egy nagy kockázatot vállalni.

Mailchimp jól mondja:

[D]ne viccelődj – az erőltetett humor rosszabb lehet a semminél. Ha nem biztos benne, maradjon egyenes arc.

(Kiemelés az enyém)

Hozzáférhető jelölés írása

Könnyen elkölthetnénk egy egész cikket a kisegítő lehetőségekről és annak a technikai íráshoz való viszonyáról. A fenébe is, a kisegítő lehetőségek gyakran szerepelnek a tartalomstílusú útmutatókban, beleértve a tartalomstílusú útmutatókat is microsoft és a MailChimp.

Ön fejlesztő, és valószínűleg már sokat tud a kisegítő lehetőségekről. Még az is lehet, hogy Ön a szorgalmasabb fejlesztők közé tartozik, akik a kisegítő lehetőségeket munkafolyamatának központi részévé teszik. Ennek ellenére hihetetlen, hogy a kisegítő lehetőségek milyen gyakran háttérbe szorulnak, bármennyire is tudjuk, mennyire fontos, hogy minden képességet magában foglaló online élményeket elérhetővé tegyük.

Tehát, ha úgy találja, hogy valaki más szövegírását implementálja a kódjába, dokumentációt ír más fejlesztőknek, vagy akár UI másolja le magát, ügyeljen néhány alapvető akadálymentesítési bevált gyakorlatra, mivel ezek kiegészítik a technikai íráshoz szükséges összes többi tanácsot.

Dolgok mint:

Andy Bell kínál néhányat viszonylag apró dolgokat tehet a tartalom hozzáférhetőbbé tétele érdekében, és megéri rászánni az idejüket. És csak a rúgások miatt, John Rhea néhány ügyes szerkesztési trükköt mutat be amelyek akkor lehetségesek, ha szemantikus HTML-elemekkel dolgozunk.

Következtetés

Ez hat módszer volt annak bemutatására, hogy a technikai írás és a fejlesztés hogyan esik egybe. Bár a példák és tanácsok talán nem rakétatudományok, remélem, hasznosnak találtad őket, legyen szó más fejlesztőkkel való együttműködésről, saját munkád karbantartásáról, saját példány megírásáról, vagy akár projektjavaslat készítéséről, stb. dolgokat.

A lényeg: ha fejleszti írási készségeit, és egy kis extra erőfeszítést tesz az írásba, valójában jobb fejlesztővé válhat.

Műszaki írási források

Ha érdekel a műszaki írás:

Ha érdekel a szövegírás:

Ha érdekel a mikromásolat:

Ha professzionális stíluskalauzt szeretne használni írása javítására:

Ha érdekel, hogy írjon a hozzáférhetőségről: