Műszaki írás kezdőknek - AZ útmutató a technikai blogolás alapjaihoz

Ha szereti az írást és a technológiát, a szakmai írás megfelelő karrier lehet az Ön számára. Ez is valami más, amit tehetsz, ha szereted a technikát, de nem igazán szeretsz egész nap kódolni.

A technikai írás akkor is lehet az Ön számára, ha szereti a tanulást mások tanításával, a nyílt forráskódú projektekhez való közreműködéssel és mások megtanításával, vagy alapvetően élvezi az összetett fogalmak egyszerű megmagyarázását az írásán keresztül.

Merüljünk el az alapok között, és ismerkedjünk meg azzal, hogy mit érdemes tudni és figyelembe venni a technikai írás megkezdéséhez.

Tartalomjegyzék

Ebben a cikkben a következőket vesszük szemügyre:

  • Mi a technikai írás
  • A műszaki írás előnyei
  • Szükséges készségek ahhoz, hogy műszaki íróként rendelkezzenek
  • A műszaki írás folyamata
  • Platformok cikkei közzétételéhez
  • Műszaki író tanfolyamok
  • Műszaki írói fórumok és közösségek
  • Néhány csodálatos technikai író, akit követni kell
  • Végső szavak és hivatkozások

Mi a műszaki írás?

A technikai írás olyan részletorientált oktatás nyújtásának művészete, amely segít a felhasználóknak megérteni egy adott készséget vagy terméket.

És műszaki író az, aki ezeket az utasításokat, más néven műszaki dokumentációnak vagy oktatóanyagnak írja. Ez tartalmazhat felhasználói kézikönyveket, online támogatási cikkeket vagy belső dokumentumokat a kódolók / API fejlesztők számára.

A műszaki író úgy kommunikál, hogy bemutatja a technikai információkat, hogy az olvasó ezeket az információkat rendeltetésszerűen felhasználhassa.

A műszaki írás előnyei

A műszaki írók egész életen át tanulnak. Mivel a munka magában foglalja az összetett fogalmak egyszerű és egyértelmű megfogalmazását, jól kell ismernie azt a szakterületet, amelyről ír. Vagy hajlandó megismerni.

Ez nagyszerű, mert minden egyes új műszaki dokumentummal, amelyet kutat és ír, szakértővé válik e témában.

A technikai írás a felhasználói empátia jobb érzését is nyújtja. Segít jobban odafigyelni arra, hogy mit éreznek a termék olvasói vagy felhasználói, és nem arra, hogy mit gondol.

Pénzt kereshet technikai íróként is, ha hozzájárul a szervezetekhez. Íme néhány olyan szervezet, amely fizet Önnek, hogy írjon nekik, például a Smashing Magazine, az AuthO, a Twilio és a Stack Overflow.

Mindezek mellett hozzájárulhat a nyílt forráskódú közösségekhez és részt vehet olyan fizetett nyílt forráskódú programokban, mint a Google Season of Docs és az Outreachy.

Felveheti a műszaki írást is teljes munkaidőben - sok vállalatnak szüksége van valakire, aki rendelkezik ilyen képességekkel.

A műszaki íróként szükséges készségek

Értse meg a megfelelő angol nyelv használatát

Mielőtt belegondolna az írásba, el kell ismernie az angolt, annak igeidőket, írásmódokat és az alapvető nyelvtant. Olvasói nem akarnak elolvasni egy cikket, amely tele van helytelen nyelvtanral és rossz szóválasztással.

Tudja, hogyan magyarázza el világosan és egyszerűen a dolgokat

A funkció megvalósításának ismerete nem feltétlenül jelenti azt, hogy egyértelműen kommunikálni tudja a folyamatot másokkal.

Ahhoz, hogy jó tanár lehessen, empatikusnak kell lennie, képesnek kell lennie arra, hogy tanítsa vagy leírja a kifejezéseket a közönségnek megfelelő módon.

Ha nem tudja megmagyarázni egy hatévesnek, akkor maga sem érti. Albert Einstein

Rendelkezzen némi írási készséggel‌‌

Hiszem, hogy írók készülnek, nem születnek. És csak akkor lehet megtanulni írni, ha valóban ír.

Soha nem tudhatod, hogy van benned olyan írás, amíg tollat ​​nem teszel papírra. És csak egy módon lehet megtudni, van-e valamilyen íráskészsége, és ez az írás.

Ezért arra bátorítalak benneteket, hogy ma kezdjék el írni. Választhat, hogy bármelyik platformmal kezdem, amelyet ebben a szakaszban felsoroltam, hogy megnyújtsa az írói izmokat.

És természetesen az is óriási előny, ha némi tapasztalattal rendelkezünk egy műszaki területen.

A műszaki írás folyamata

Elemezze és értse meg, kik az olvasói

A legnagyobb szempont, amelyet technikai cikk írásakor figyelembe kell venni, a tervezett / várható közönség. Mindig az elméd élén kell állnia.

Egy jó műszaki író az olvasó kontextusa alapján ír. Tegyük fel például , hogy kezdőknek szóló cikket ír. Fontos, hogy ne feltételezzük, hogy ők már ismernek bizonyos fogalmakat.

A cikket a szükséges előfeltételek ismertetésével kezdheti. Ez biztosítja, hogy olvasói rendelkezzenek (vagy elsajátíthassák) a szükséges ismereteket, mielőtt közvetlenül a cikkbe merülnének.

Hasznos forrásokra mutató linkeket is felvehet, hogy olvasói csak egy kattintással megszerezhessék a szükséges információkat.

Annak érdekében, hogy megtudja, kinek ír, minél több információt kell összegyűjtenie arról, hogy ki fogja használni a dokumentumot.

Fontos tudni, hogy a közönség rendelkezik-e szakértelemmel a területen, a téma teljesen új számukra, vagy valahol a kettő közé esik.

Olvasóinak is megvannak a maguk elvárásai és igényei. Meg kell határoznia, hogy az olvasó mit keres, amikor elkezdi olvasni a dokumentumot, és mit hoz ki belőle.

Az olvasó megértése érdekében az írás megkezdése előtt tegye fel magának a következő kérdéseket:

  • Kik az olvasóim?
  • Mi kell nekik?
  • Hol fognak olvasni?
  • Mikor fognak olvasni?
  • Miért fognak olvasni?
  • Hogyan fognak olvasni?

Ezek a kérdések segítenek abban is, hogy elgondolkodjon olvasójának tapasztalatairól, miközben elolvassa az írását, amelyről most még többet beszélünk.

Gondoljon a felhasználói élményre

A felhasználói élmény ugyanolyan fontos egy műszaki dokumentumban, mint bárhol az interneten.

Most, hogy ismeri közönségét és igényeit, ne feledje, hogy maga a dokumentum hogyan szolgálja az igényeiket. Olyan egyszerű figyelmen kívül hagyni, hogy az olvasó hogyan fogja használni a dokumentumot.

Írás közben folyamatosan lépjen hátrébb, és tekintse meg a dokumentumot, mintha Ön lenne az olvasó. Kérdezd meg magadtól: Hozzáférhető-e? Hogyan fogják használni olvasói? Mikor fogják használni? Könnyű navigálni?

A cél egy olyan dokumentum megírása, amely egyszerre hasznos és használható az olvasók számára.

Tervezze meg a dokumentumot

Figyelembe véve, hogy kik a felhasználói, akkor ezt konceptualizálhatja és megtervezheti a dokumentumot.

Ez a folyamat számos lépést tartalmaz, amelyeket most áttekintünk.

Végezzen alapos kutatást a témával kapcsolatban

A dokumentum megtervezése közben meg kell kutatnia azt a témát, amelyről ír. Rengeteg erőforrás található, amelyek csak egy Google-kereséssel elérhetők, és amelyekből mélyebb betekintést nyerhet.

Ne érjen kísértés, hogy mások műveit vagy cikkeit feloldja, és sajátjaként adja át, mivel ez plágium. Inkább használja ezeket az erőforrásokat referenciaként és ötletként a munkájához.

A lehető legtöbbet keresse a Google-on, szerezzen tényeket és számokat kutatási folyóiratokból, könyvekből vagy hírekből, és gyűjtsön minél több információt a témájáról. Ezután elkezdheti a vázlat készítését.

Készítsen vázlatot

A dokumentum tartalmának felvázolása, mielőtt kibővítené, fokozottabban segít írni. Ez lehetővé teszi a gondolatok rendszerezését és az írás céljainak elérését is.

A vázlat segíthet abban is, hogy meghatározza, mit szeretne olvasói kihozni a dokumentumból. És végül létrehoz egy ütemtervet az írás befejezéséhez.

Szerezzen be releváns grafikákat / képeket

A vázlat használata nagyon hasznos a különböző virtuális segédeszközök (infografikák, gifek, videók, tweetek) azonosításához, amelyeket be kell ágyaznia a dokumentum különböző szakaszaiba.

És sokkal könnyebbé teszi az írási folyamatot, ha kéznél tartja ezeket a releváns grafikákat.

Írja a helyes stílusban

Végül elkezdheti írni! Ha elvégezte ezeket a lépéseket, az írásnak sokkal könnyebbé kell válnia. De még mindig meg kell győződnie arról, hogy az írás stílusa megfelelő-e egy műszaki dokumentumhoz.

Az írásnak hozzáférhetőnek, közvetlennek és szakszerűnek kell lennie. A virágos vagy érzelmi szöveget nem fogadjuk el egy műszaki dokumentumban. Ennek a stílusnak a fenntartásában az alábbiakban felsorolunk néhány legfontosabb jellemzőt, amelyet érdemes ápolnia.

Használja az Aktív hang lehetőséget

Célszerű az aktív hangokat használni a cikkekben, mivel könnyebben olvasható és érthetőbb, mint a passzív hang.

Aktív hang azt jelenti, hogy az alany a mondat az egyik aktívan végző akció az ige. A passzív hang azt jelenti, hogy az alany az ige cselekvésének befogadója .

Íme egy példa a passzív hangra : A dokumentációt minden webfejlesztőnek évente hatszor el kell olvasnia.

És itt van egy példa az aktív hangzásról : Minden webfejlesztőnek el kell olvasnia ezt a dokumentációt évente 6 alkalommal.

Óvatosan válassza a szavait

Fontos a szóválasztás. Ügyeljen arra, hogy a kontextushoz a legjobb szót használja. Kerülje az olyan névmások túlzott használatát, mint az 'it' és az 'this', mivel az olvasónak nehézségei lehetnek azonosítani, hogy mely névekre hivatkoznak.

Kerülje a szleng és vulgáris nyelvezetet is - ne felejtse el, hogy szélesebb közönségnek ír, akinek kedve és kulturális hajlama eltérhet a tiétől.

Kerülje a túlzott kifejezést

Ha Ön a szakterületének szakértője, akkor könnyen használható ismerős zsargonja anélkül, hogy észrevenné, hogy zavaró lehet más olvasók számára.

Kerülje a korábban meg nem magyarázott rövidítések használatát is.

Íme egy példa :

Kevésbé egyértelmű: A PWA- kat valóban a több platformos fejlesztés jövőjének tekintik. Elérhetőségük Androidon és iOS-en egyaránt a jövő alkalmazásává teszi őket.

Továbbfejlesztve: A progresszív webalkalmazások (PWA) valóban a multiplatformos fejlesztés jövője. Elérhetőségük mind Android, mind iOS rendszeren a PWA-t a jövő alkalmazásának teszi .

Sima nyelv használata

Használjon kevesebb szót, és írjon úgy, hogy minden olvasó megértse a szöveget. ‌‌ Kerülje a nagy, hosszú szavakat. Mindig próbáljon a lehető legtisztábban magyarázni a fogalmakat és kifejezéseket.

Vizuális formázás

A fal szövege nehezen olvasható. A legegyértelműbb utasítások is elveszhetnek egy rossz vizuális megjelenítésű dokumentumban.

Azt mondják, egy kép ezer szót ér. Ez még a műszaki írásban is igaznak tűnik.

De nem akármilyen kép méltó egy műszaki dokumentumhoz. A technikai információkat csak szövegben lehet nehéz átadni. Egy jól elhelyezett kép vagy ábra tisztázhatja a magyarázatot.

Az emberek is imádják a képeket, ezért segít a megfelelő helyekre illeszteni őket. Vegye figyelembe az alábbi képeket:

Először is, itt van egy blogrészlet, látvány nélkül:

Itt egy részlet ugyanabból a blogból, de látványokkal

Képek hozzáadása a cikkekhez a tartalmat jobban összekapcsolhatóvá és könnyebben érthetővé teszi. A képek mellett szükség esetén használhat gifeket, hangulatjeleket, beágyazásokat (közösségi média, kód) és kódrészleteket is.

Az átgondolt formázás, sablonok, képek vagy diagramok a szöveget is hasznosabbá teszik olvasói számára. Az alábbi referenciákat a @Bolajiayodeji technikai írási sablonhoz tekintheti meg.

Gondos felülvizsgálatot végezzen

Bármilyen típusú helyes írásnak mentesülnie kell a helyesírási és nyelvtani hibáktól. Ezek a hibák nyilvánvalónak tűnhetnek, de nem mindig könnyű észrevenni őket (különösen hosszú dokumentumok esetén).

Mindig ellenőrizd a helyesírást (tudod, pontozd meg a lényeidet, és keresztezd a Ts-t), mielőtt a "közzététel" gombra kattintasz.

Számos ingyenes eszköz létezik, például a Grammarly és a Hemingway alkalmazás, amelyek segítségével ellenőrizheti a nyelvtani és helyesírási hibákat. Megoszthatja cikkelyének vázlatát valakivel, akit közzététel előtt lektorálni kell.

Hol lehet közzétenni a cikkeket

Most, hogy elhatározta, hogy a technikai írást választja, íme néhány jó platform, ahol elkezdheti ingyen elhelyezni a technikai tartalmat. Segíthetnek abban is, hogy vonzó portfóliót építsenek ki a leendő munkaadók számára, hogy ellenőrizzék őket.

A Dev.to egy több ezer technikás közösség, ahol az írók és az olvasók egyaránt értelmesen elkötelezhetik magukat, és megoszthatják ötleteiket és forrásaikat.

A Hashnode az én blog-platformom, fantasztikus előnyökkel , például egyéni domain-hozzárendeléssel és interaktív közösséggel. Blog létrehozása ezen a platformon szintén egyszerű és gyors.

A freeCodeCamp nagyon nagy közösségi és közönségeléréssel rendelkezik, és remek hely cikkei közzétételéhez. Jelentkeznie kell azonban a publikáláshoz néhány korábbi írásmintával.

Jelentkezésed akár elfogadható, akár elutasítható, de ne csüggedj. Később bármikor újra jelentkezhet, ha jobb lesz, és ki tudja? Elfogadhatnád.

Ha mégis nekik írsz, a közzététel előtt átnézik és szerkesztik a cikkeidet, hogy a lehető legcsiszoltabb cikkeket tedd közzé. A cikkeket a közösségi média platformjaikon is megosztják, hogy minél több ember olvassa el őket.

A Hackernoon több mint 7000 íróval rendelkezik, és nagyszerű platform lehet számodra, hogy elkezdhesd közzé cikkeidet a közösség több mint 200 000 olvasójának.

A Hacker Noon támogatja az írókat azáltal, hogy lektorálja cikkeiket, mielőtt közzétenné őket a platformon, és segít elkerülni a gyakori hibákat.

Műszaki író tanfolyamok

Csakúgy, mint minden más területen, itt is vannak különféle folyamatok, szabályok, bevált gyakorlatok stb.

A technikai írással kapcsolatos tanfolyam végigvezeti Önt minden olyan dolgon, amelyet meg kell tanulnia, és jelentős önbizalmat adhat az írás útjának megkezdéséhez.

Íme néhány technikai író tanfolyam, amelyet megnézhet:

  • Google műszaki írás tanfolyam (ingyenes)
  • Udemy Műszaki Írás Tanfolyam (Fizetett)
  • Hashnode műszaki írás Bootcamp (ingyenes)

Műszaki író fórumok és közösségek

Egyedül tudunk ennyire keveset, együtt, annyit tenni ~ Helen Keller

Előnyös, ha egy közösség vagy fórum tagja leszel olyan emberekkel együtt, akik ugyanolyan szenvedéllyel rendelkeznek, mint te. Visszajelzéseket, javításokat, tippeket kaphat, sőt, néhány stílustippet is megtudhat a közösség más íróitól.

Íme néhány közösség és fórum, amelyekhez csatlakozhat:

  • Hashnode
  • Dev.to
  • Műszaki írásvilág
  • Műszaki írói fórum
  • Írja meg a Docs fórumot

Néhány csodálatos műszaki író, akit követni kell

Műszaki író utam során olyan nagyszerű írókat követtem, akiknek írási útja, következetessége és stílusa inspirál.

Ezek azok az írók, akikre utánanézek, és virtuális mentoroknak tartom a műszaki írást. Néha elvetik azokat a technikai írási tippeket, amelyeket hasznosnak találok, és amelyekből sokat tanultam.

Íme néhány ilyen író (hiperhivatkozással a twitter fogantyúival):

  • Quincy Larson
  • Edidiong Asikpo
  • Catalin Pit
  • Victoria Lo
  • Bolaji Ayodeji
  • Amruta Ranade
  • Chris Bongers
  • Colby Fayock

Utolsó szavak

A műszaki tartalom közzétételéhez nem kell műszaki írásbeli végzettség. A portfólió felépítése és gyakorlati tapasztalatok megszerzése közben elkezdhet írni a saját blogján és a nyilvános GitHub-tárhelyein.

Tényleg - Csak kezdd el írni.

Gyakoroljon új dokumentumok létrehozásával a meglévő programok vagy projektek számára. Számos nyílt forráskódú projekt található a GitHubon, amelyeket megnézhet és hozzáadhat a dokumentációjukhoz.

Van olyan alkalmazás, amelyet szeretsz használni, de a dokumentációja rosszul van megírva? Írja meg sajátját, és ossza meg online visszajelzés céljából. Gyorsan beállíthatja blogját a hashnode-on, és elkezdhet írni.

Megtanulsz írni írással, olvasva és gondolkodva arról, hogy az írók miként alkották meg szereplőiket és találták fel a történeteiket. Ha nem vagy olvasó, ne is gondolj arra, hogy író vagy. - Jean M. Auel

A műszaki írók mindig tanulnak . Azáltal, hogy új tantárgyakba merül és külső visszajelzéseket kap, a jó írók soha nem hagyják abba a csiszolást.

Természetesen a jó írók is falánk olvasók. A sokat olvasott vagy sokat használt dokumentumok áttekintésével a saját írásod mindenképpen javulni fog.

Alig várom, hogy megtekinthesse műszaki cikkeit!

Hivatkozások

Bevezetés a műszaki írásba‌‌

Hogyan szerkesszünk egy műszaki cikket‌‌

A közönség megértése, miért és hogyan

‌‌Technikai írás sablon

Remélem, ez hasznos volt. Ha igen, kövessen a Twitteren, és tudassa velem!