Mi a műszaki írás? Teljes útmutató

Amikor egy új kütyüvel bajlódsz, a kézikönyvért nyúlsz.

Ha elakadsz a szoftver beállításával, nézd meg a súgóoldalakat.

Amikor az autója furcsa hangot ad ki, átlapozza a kesztyűtartó kézikönyvét.

Mindezek példák a következőkre műszaki írás - valami, amire minden nap támaszkodunk, de ritkán gondolunk rá.

A Glassdoor szerint egy műszaki író a SpaceX-nél a következő összegeket keresi $88,000 és $138,000 között évente. 

A legtöbb ember még mindig nem érti, hogy mi is valójában a műszaki írás.

Ez nem csak gépelés utasítások.

Ez nem csak fordítás a mérnöki beszédet egyszerű angolra.

És ez még csak nem is csak a létrehozása felhasználói kézikönyvek vagy súgó dokumentumok. 

Mi is az a műszaki írás? Miben különbözik más írástípusoktól? Melyek a különböző formái? Hogyan válhat műszaki íróvá? És hogyan segíthet a mesterséges intelligencia ezen az úton? 

Mindezzel - és még sok mással - foglalkozunk ebben a blogban. Merüljünk el! 

Mi a műszaki írás?

A laikusok számára a technikai írás azt jelenti, hogy a bonyolult és részletes témákat úgy magyarázzuk el, hogy bárki (a megfelelő háttérrel) követni tudja őket. 

Például, ez magában foglalja:

• Felhasználói kézikönyvek - Az a füzet, amit a telefonoddal együtt kaptál? Az a technikai írás.
• API dokumentáció - A fejlesztőknek is szükségük van utasításokra. Az API-k nem magyarázzák meg magukat.
• Műszaki jelentések - A mérnökök és tudósok ezekre támaszkodnak a kutatások és eredmények megosztása érdekében.

A műszaki írás nem csak arról szól, hogy mit írsz. hogyan írja meg. Használja:

• Imperatív hangulat - Ahelyett, hogy "Meg kell kattintani a gombot," ez csak "Kattints a gombra." 

• Passzív hang (ha szükséges) - Ha nem számít, hogy ki tette a cselekvést, a passzív hang segít. "A fájlt törölték" jobban működik, mint "Valaki törölte a fájlt" ha a fókusz a fájlon van.

Egyesek azt gondolják, hogy a műszaki írás csak a SaaS-termékek vagy a technológiai blogok számára történő írást jelenti. 

De ez nem a marketingről vagy a történetmesélésről szól. 

Műszaki írás nagyon különböző típusai vannak (rövidesen tárgyaljuk) - mindegyiknek ugyanaz a célja: az információ pontos, világos és funkcionális módon történő bemutatása. 

Hogyan különbözik a műszaki írás más írásmódoktól?

Értsünk meg hat szempontot, amelyek alapján a műszaki írás különbözik a többi írásmódtól.

A kreatív írók kétértelműséget vagy metaforákat használnak, hogy a közönség számára vonzó tényezőt tartalmazzanak. 

A műszaki írók nem törekednek semmiféle kétértelműségre. 

A kreatív kifejezéssel szemben a tisztaságot akarják előtérbe helyezni, de ez a munka természete. 

Miért elengedhetetlen a műszaki írás a különböző iparágakban

Képzelje el, hogy egy pilóta a repülés közben olvassa ezt a kézikönyvet, amikor valamit sürgősen meg kell értenie:

"A tolóerő-vektorálás beállítása az aszimmetrikus meghajtási anomália kompenzálására az 5.3b szabványos eltérési protokoll végrehajtásával, a légköri sűrűségváltozók figyelembevételével"

Vagy képzelje el, hogy egy sebész pillanatokkal egy kritikus műtét előtt átnézi az eljárási irányelveket: 

"A fasciális síkokkal párhuzamos metszés, figyelembe véve a mögöttes neurovaszkuláris struktúrákat, miközben a vérzéscsillapítást a metszési szekvencia során végig fenntartja." 

Még ha orvosok vagy pilóták is, akik egész pályafutásuk során ezt tanulták, vészhelyzetben nem szívesen olvasnák ezt. 

Zavart és frusztrációt okoz, amit mindenki szeretne elkerülni, bármilyen helyzetben is legyen.

Nézzünk meg öt fő okot, amiért a műszaki szövegírás elengedhetetlen: 

1. Kockázatcsökkentés és megfelelés - Az olyan iparágakban, mint az egészségügy, a pénzügy és a repülés, a hibák nem csak költségesek, hanem akár halálosak is lehetnek. 
   • Például, Mi történik, ha egy ápoló félreértelmezi az adagolási utasításokat a nem egyértelmű megfogalmazás miatt? A megfelelő dokumentáció megelőzi ezeket a hibákat. 

2. Tudás megőrzése és átadása - Az emberek elhagyják a munkahelyüket, előléptetik őket, vagy nyugdíjba mennek. De mi történik a fejükben lévő tudással? Ezeket megfelelően dokumentálják a műszaki írás segítségével. Egy jól dokumentált folyamat azt jelenti, hogy a következő személy anélkül léphet be, hogy a nulláról kellene kezdenie.

3. Ügyfélelégedettség és csökkentett támogatási költségek - Próbáltál már beállítani egy új eszközt, és végül egy random YouTube oktatóanyagot néztél, mert a kézikönyvnek semmi értelme nem volt? A rossz dokumentáció frusztrálja az ügyfeleket, és felesleges hívásokkal terheli az ügyfélszolgálatot. Egy jól megírt útmutató mindezt megmenti. 

4. Jogi védelem - A szerződések, irányelvek és biztonsági irányelvek bizonyítékként szolgálnak a jogvitákban.
   • Például, ha egy vállalatot beperelnek egy hibás termék miatt, az ügyvédek először a dokumentációt ellenőrzik. Figyelmeztettek-e a használati utasításban a kockázatokra? Világosan körvonalazódtak-e a biztonsági eljárások? Ha nem, a vállalat bajban van.

5. Hatékonyságnövekedés a szabványosítás révén - Képzeljünk el egy olyan vállalatot, ahol minden részleg más-más rendszert követ ugyanarra a feladatra. Az egyik csapat táblázatokon követi az adatokat, egy másik egyedi szoftvert használ, egy harmadik pedig egyszerűen "megjegyzi a dolgokat". Ez egy zűrzavar. A műszaki írás gondoskodik arról, hogy a folyamatok szabványosíthatóak, megismételhetőek és skálázhatóak legyenek.

A műszaki írás alapvetően segít megelőzni a zavart, időt takarít meg, és biztonságban tartja az embereket. 

A műszaki írás típusai (példákkal)

Sokan hallják, hogy "műszaki írás" és azonnal száraz, robotszerű használati útmutatókra gondolunk - olyanokra, amelyeket senki sem olvas el, hacsak nem akadnak el teljesen. 

De a műszaki írás ennél sokkal több. 

A valóságban szinte minden iparágban létezik, és sokféle formában, mindegyik külön célt szolgál.

Íme a hat leglényegesebb műszaki írástípus (példákkal):

1. Műszaki dokumentáció - Ez a klasszikus típus. Felhasználói kézikönyveket, termékismertetőket és hibaelhárítási utasításokat tartalmaz.  
   • Például, Most vettél egy vadonatúj eszpresszógépet, és zavarban vagy a sok gomb miatt. Találgatás helyett inkább kinyitja a használati útmutatót, és követi a lépésről lépésre követett útmutatót, hogy elkészítse az első csészét.
     
2. Folyamat dokumentáció - Minden vállalatnak vannak munkafolyamatai, de ha ezek a munkafolyamatok csak valakinek a fejében léteznek, az katasztrófára vár. Ezeket SOP-oknak nevezik. 
   • Például, El kell készítened egy pékség jellegzetes kovászát. SOP nélkül minden kenyér más lenne. Szerencsére a SOP minden egyes lépést részletez - pontos méréseket, kelesztési időt, sütési hőmérsékletet - minden alkalommal.
     
3. API dokumentáció - Ha a szoftver az agy, API-k (Application Programming Interfaces) az idegrendszer. 
   • Például, Egy fuvarmegosztó alkalmazás valós idejű forgalmi adatokat szeretne, ezért integrálja a Google Maps API-ját. Egyértelmű API-dokumentumok nélkül végtelen próbálkozással és hibázással kellene szembenézniük.
     
4. Tudományos/kutatási cikkek - Ezeket a kutatók írják, de a világ számára is olvashatónak kell lenniük.  
   • Például, Egy új rákkezelés ígéretesnek tűnik, de mielőtt alkalmaznák, a tudósoknak közzé kell tenniük a kutatásokat a hatásáról, a mellékhatásairól és a túlélési arányáról. Mások felülvizsgálják az adatokat, hogy ellenőrizzék azokat.
     
5. Fehér dokumentumok és esettanulmányok - A fehér könyvek a műszaki világ "meggyőző érvei". Az esettanulmányok még tovább mennek, valós sikertörténeteket mutatnak be, tényleges eredményekkel. 
   • Például, Egy kiberbiztonsági cég fehér könyvben figyelmeztet egy új banki fenyegetésre. Egy hónappal később egy esettanulmányt osztottak meg arról, hogyan állítottak meg egy támadást az eszközükkel. A bankok elkezdenek figyelni.
     
6. Szabályozási/megfelelőségi dokumentáció - Az egészségügy, a pénzügy és a gyártás a szabályozásokra támaszkodik. A megfelelőségi dokumentumok segítenek a vállalatoknak a törvények betartásában, elkerülve a bírságokat, a pereket és a nyilvános katasztrófákat.
   • Például, Egy gyógyszergyártó cégnek bizonyítania kell, hogy egy új fájdalomcsillapító biztonságos, mielőtt eladná azt. Az összetevők, az adagolás és a mellékhatások felsorolását tartalmazó dokumentumokat nyújtanak be, hogy elkerüljék a jogi problémákat.

A műszaki íráshoz szükséges kulcskompetenciák

Ha valaha is megtanítottad a nagyszüleidnek, hogyan kell használni egy okostelefont anélkül, hogy hülyének éreznék magukat, akkor lehetsz műszaki író, mert ez az alapkészség.

Minden más készség tanulható. Íme egy lista azokról a készségekről, amelyekkel egy műszaki írónak rendelkeznie kell:

• Kutatási képességek - Nem kell mindent tudnia, de tudnia kell, hogyan találhat pontos és megbízható információkat.
  
• Közönségelemzés - Azzal, hogy tudod, kik az olvasóid, mit tudnak már, és mit kell elérniük, hasznos lesz az írásod. Mert ahogyan egy szoftverfrissítést elmagyarázol egy fejlesztőnek, az nem ugyanaz, mint ahogyan egy ügyfélnek elmagyaráznád.
  
• Világos kommunikáció/egyszerű nyelvtudás - A műszaki írás nem arról szól, hogy okosnak tűnjünk - hanem arról, hogy mások okosnak érezzék magukat. Ez a szakzsargon elhagyását, egyszerű nyelvezetet és olyan világos írást jelent, hogy az olvasónak soha ne kelljen kitalálnia, mire gondol.
  
• Információs architektúra - Az olvasók nem mindig az elejétől a végéig olvasnak, hanem átfutnak. Meg kell értenie, hogyan szervezze a tartalmat címsorokkal, felsorolással és logikus felépítéssel, hogy az információ könnyen megtalálható és emészthető legyen.
  
• Vizuális kommunikáció - Néha egy kép gyorsabban elmagyaráz valamit, mint egy bekezdés. A folyamatábrák, a kommentált képernyőképek és az infografikák még a legzavarosabb fogalmakat is leegyszerűsíthetik. A jó műszaki író tudja, mikor kell írni és mikor kell mutatni.
  
• Szerszám jártasság - A megfelelő eszközök ismerete felgyorsítja a folyamatot. A dokumentációs szoftverek közé tartozik például a MadCap Flare vagy a Confluence, a tervezőeszközök közé pedig a Snagit vagy a Figma.

• Szerkesztési és felülvizsgálati készségek-Az első vázlat sosem tökéletes. A műszaki íróknak finomítaniuk kell munkájukat az egyértelműség, a pontosság és a teljesség érdekében, biztosítva, hogy minden szó a célját szolgálja. Ez arról szól, hogy a dokumentum a lehető legkönnyebben használható legyen.

Ki használja a műszaki írást? (Iparágak, amelyeknek szükségük van rá)

Íme a négy iparág, ahol a műszaki írásra van a legnagyobb szükség.

Hogyan válhatsz műszaki íróvá 

Íme egy lépésről lépésre követhető útmutató, amely segít a szakterületre való belépésben:

# 1. lépés - Ismerje meg az alapokat

Nincs szükséged kommunikációs vagy angol nyelvtudásból szerzett diplomára ahhoz, hogy belevágj.

Akár tanárként, újságíróként, mérnökként vagy akár az egészségügyben dolgozóként is belevághatsz és boldogulhatsz ezen a pályán.

Vegyen kezdőbarát tanfolyamokat és tanúsítványokat a Coursera, Udemy, vagy A Google műszaki írói tanfolyama. 

Kövesse az iparági blogokat, mint például  Írja meg a dokumentumokat és STC (Műszaki Kommunikációs Társaság).

# 2. lépés - Portfólió építése

Válasszon egy olyan terméket, amelyet naponta használ (pl. kávéfőző, fitneszalkalmazás vagy intelligens hangszóró), és írjon felhasználói kézikönyvet vagy hibaelhárítási útmutatót. 

Tökéletes lenne? Nem. 

Ez adna valami konkrétumot, amit megmutathatna? Abszolút. 

A nyílt forráskódú közösség, mint GitHub nyitott új műszaki írók számára. 

Sok projektnek nagy szüksége van a dokumentációs segítségre, és nem érdekli őket, ha új vagy. 

# 3. lépés - Szerezzen belépő szintű szerepet

Koncentráljon a "junior" vagy "associate" megnevezéssel ellátott pozíciókra az olyan platformokon, mint például a LinkedIn, Valóban, és Távolról dolgozunk. 

Ne hagyja figyelmen kívül a szerződéses állásokat sem - ezeket gyakran könnyebb megszerezni, és állandó szerepekhez vezethetnek.

# 4. lépés - Fejlessze karrierjét

Ha már van önbizalma és tapasztalata, célozza meg a vezető műszaki írói, API-írói vagy UX-írói pozíciót.

Ismerkedjen meg az olyan eszközökkel, mint a MadCap Flare, és Oxygen XML strukturált írás vagy Markdown és Git ha fejlesztőkkel szeretne együtt dolgozni. De nem kell mindent egyszerre elsajátítania.

# 5. lépés - Készüljön fel az interjúkra

• Gyakori kérdések:
  • Hogyan lehet leegyszerűsíteni egy összetett témát? → Mutasson egy előtte-utána írásmintát.
  • Milyen eszközöket használtál? Említse meg az összeset.
  • Hogyan kezeli a mérnökök visszajelzéseit? → Mondjon egy valós vagy hipotetikus példát. 

# 6. lépés - Tanulj tovább és lépj magasabb szintre

A terület folyamatosan fejlődik. Az egyik évben mindenki a wikiről beszél, a következőben pedig a docs as code-ról. 

Azok az emberek boldogulnak, akik folytatják a továbbképzést. 

Kövesse a TechWhirl és Cherryleaf a trendekért.

Kezdje el még ma. Írja újra egy termék kézikönyvét, ossza meg a LinkedIn-en, és kérjen visszajelzést.

Műszaki írói eszközök és szoftverek

A mesterséges intelligencia eszközei megkönnyítik és hatékonyabbá teszik a feladatokat - és ez a műszaki írás esetében sincs másképp.

Íme, a szakemberek által használt technikai íróeszközök:

1. Szerkesztéshez és tartalomszerkesztéshez:

1. MS Word segítségével professzionálisan formázott dokumentumokat hozhat létre a stílusok, fejlécek és kereszthivatkozások pontos vezérlésével. 
2. Google Dokumentumok lehetővé teszi, hogy több csapattag egyszerre dolgozzon ugyanazon a dokumentumon. 

2. Strukturált dokumentáció és közzététel: 

1. MadCap Flare lehetővé teszi, hogy egyetlen tartalomforrást tartson fenn, amely automatikusan közzéteszi a különböző formátumokat. 
2. Adobe FrameMaker kezeli az 500 oldalas műszaki leírást összetett táblázatokkal, speciális diagramokkal és kereszthivatkozásokkal. 

3. Csapat alapú dokumentációhoz:

1. Confluence a vállalat belső wikijévé válik, ahol a különböző részlegek karbantartják dokumentációjukat. 
2. Fogalom segít a termékcsapatnak a projektmenedzsment mellett a dokumentáció megszervezésében is. 

4. A dokumentumváltozások kezeléséhez és nyomon követéséhez:

1. GitHub lehetővé teszi a fejlesztők számára, hogy a dokumentációt a kódváltozásokkal együtt frissítsék.
2. BitBucket integrálódik a CI/CD csővezetékkel, így a dokumentáció automatikusan épül és települ minden egyes kiadással együtt.

5. A kutatás, a tartalom szerkezete és a jobb olvashatóság érdekében:

1. Esszéíró segít dokumentálni egy kifinomult algoritmust megfelelő kontextusban, magyarázatokkal és példákkal. 
2. SEO író biztosítja, hogy a nyilvános dokumentáció egységes terminológiát használjon, és kövesse a legjobb olvashatósági gyakorlatokat. 
3. AI Chat segít a műszaki írónak leegyszerűsíteni az összetett fogalmakat. Alternatív magyarázatokat javasol, és azonosítja azokat a területeket, ahol a felhasználóknak további kontextusra lehet szükségük. 

Hogyan javíthatja a mesterséges intelligencia a műszaki szövegírás hatékonyságát?

Íme, hogyan segíthet a mesterséges intelligencia a műszaki írásban: 

1. Automatizálás

Egy üres oldalról kezdeni nehéz. A mesterséges intelligencia segítségével strukturált adatokon alapuló kezdeti tartalmat készíthet.

Csökkenti a kézikönyvek, útmutatók és jelentések elkészítéséhez szükséges időt. 

Hogyan kell csinálni...

Használjon AI eszközöket, mint például AI Chatbot alapvető vázlatok vagy akár egy első vázlat elkészítéséhez.

Ezután finomítsa a nyelvezetet iparág-specifikus terminológiával, és ellenőrizze a tartalmat. 

2. Nyelvtan és egyértelműség

A mesterséges intelligencia eszközeivel ellenőrizze a szakzsargont, a passzív hangnemet és az olvashatósági problémákat. 

Így kell használni...

Futtassa a tervezeteket AI Paraphraser. Ez az eszköz segít az összetett mondatok átírásában, egyszerű nyelvi alternatívákat javasol, és javítja az általános olvashatóságot.

3. Tartalom strukturálása

A jól strukturált dokumentum megelőzi a zavart.

A mesterséges intelligencia képes logikusan rendszerezni a tartalmat azáltal, hogy csoportosítja a kapcsolódó témákat, címsorokat ad hozzá, és elrendezéseket javasol. 

Így kell használni..

Használja a AI esszéíró jelentések, kézikönyvek és dokumentációk készítéséhez.

Következtetés

A műszaki írók a "mérnöki nyelvet" lefordítják "emberi nyelvre".

Ezért tudják a pilóták biztonságosan leszállítani a repülőgépeket anélkül, hogy egy 10 000 oldalas kézikönyvet olvasnának a repülés közben, ezért összpontosítanak a sebészek az életmentésre ahelyett, hogy rejtélyes használati utasításokat fejtenének meg, és ezért használhatod a csodás kávéfőzőt anélkül, hogy véletlenül gejzír keletkezne a konyhádban. 

Összetett világunkban az egyértelmű kommunikáció elengedhetetlen.

A jó műszaki írás időt, pénzt, frusztrációt és néha életeket is megment (orvosi és biztonsági vonatkozásban).

A jövőben több videót láthatunk majd interaktív útmutatók és dokumentumok formájában, amelyek alkalmazkodnak a szakértelem szintjéhez. 

Ha a műszaki írói izmait szeretné megmozgatni, válasszon valami bonyolult dolgot, amit jól ért - például hogyan működik a fotoszintézis, a fociban az offside-szabály vagy akár a tökéletes szuflé elkészítése -, és magyarázza el egy barátjának a lehető legegyszerűbben és legvilágosabban. 

Ha ezt értik meg ahelyett, hogy elkerekedett szemmel néznének rád, gratulálok!

Felfedezte a műszaki író legfőbb képességét: a bonyolultat nem bonyolulttá tenni.

Segítségre van szüksége? Kimutathatatlan AI eszközök finomítják az írásodat, és hibátlanul tartják. Próbálja ki őket most!

Nyugodtan fedezze fel a AI Detector és Humanizer az alábbi widgetben!