Megjegyzések:
- Ez a fejezet, valamint a műszaki írásról szóló tankönyv többi része a műszaki írás készségeire összpontosít. Az itt szereplő műszaki tartalom sikere, pontossága vagy aktualitása nem garantált.
- Ezt a fejezetet az OpenAI ChatGPT fordította. Kérjük, jelezd a nyelvi problémákat az admin@mcmassociates.io címen.
- Kérjük, kattints ide, hogy segíts David McMurrey számára a webtárhely költségeinek fedezésében: adományozz bármilyen összeget! Az Online Technical Writing továbbra is ingyenes marad.
Ennek a fejezetnek a középpontjában a műszaki írás egyik legfontosabb felhasználási területe áll — az utasítások. Ahogy tudod, az utasítások lépésről lépésre magyarázzák el, hogyan kell valamit megcsinálni: hogyan kell megépíteni, működtetni, megjavítani vagy karbantartani dolgokat.
Mindenképpen tekintsd meg a példákat.
Utasításokat írsz munkához vagy egy műszaki írás kurzusra? Próbáld ki ezt az utasítástervezési útmutatót.
Utasítások írása
A műszaki írás egyik leggyakoribb és legfontosabb felhasználási területe az utasítások készítése — azok a lépésről lépésre haladó magyarázatok, amelyek bemutatják, hogyan kell dolgokat összeszerelni, működtetni, javítani vagy rutinszerű karbantartást végezni rajtuk. Ám bármennyire is egyszerűnek és intuitívnak tűnik, az utasítások gyakran a legrosszabbul megírt dokumentumok közé tartoznak. Hozzám hasonlóan valószínűleg neked is sok bosszantó élményed volt már a rosszul megírt utasításokkal. A fejezet következő része nem egy tévedhetetlen, hibabiztos útmutató az utasításíráshoz, de bemutatja azokat a technikákat, amelyeket a szakemberek a legjobbnak tartanak.
Végső soron a jó utasításírás megköveteli:
- Világos, egyszerű fogalmazást
- Az eljárás alapos megértését minden műszaki részletével együtt
- Annak képességét, hogy bele tudd képzelni magad az olvasó — az utasításokat használó személy — helyzetébe
- Annak képességét, hogy részleteiben vizualizáld az eljárást, és ezt a tudatosságot papírra tudd vetni
- Végül azt a hajlandóságot, hogy megtegyél egy plusz lépést, és kipróbáld az utasításaidat azon a közönségen, akinek írtad őket.
Eddigre valószínűleg már tanulmányoztad a címsorokat, listákat és speciális figyelmeztetéseket — ezekkel az eszközökkel egy utasítássor megírása talán magától értetődőnek tűnik. Egyszerűen bontsd a magyarázatot számozott, függőleges listákra, szúrj be néhány speciális figyelmeztetést a nyilvánvaló pontokon, és kész is! Nos, nem egészen, de ez egy nagyszerű kezdet. Ez a fejezet az utasítások néhány olyan jellemzőjét vizsgálja meg, amelyek összetettebbé tehetik őket. Ezeket a szempontokat felhasználhatod saját utasításaid megtervezéséhez is.
NotebookLM által generált infografika erről a fejezetről
Előzetes megfontolások
Egy utasításíró projekt elején fontos meghatározni annak az eljárásnak a szerkezetét vagy jellemzőit, amelyről írni fogsz.
Közönség és helyzet. A folyamat korai szakaszában határozd meg az utasításaid közönségét és a helyzetet. Ne feledd, hogy a közönség meghatározása magában foglalja a téma iránti jártasság szintjének meghatározását is, valamint egyéb hasonló részleteket. Lásd a közönségekről szóló ismertetést és a közönség meghatározásához használható lépéseket.
A legfontosabb, hogy ha íráskurzuson veszel részt, akkor készítened kell egy leírást a közönségedről, és azt csatolnod kell az utasításaidhoz. Ez lehetővé teszi az oktató számára, hogy értékelje az utasításaidat abból a szempontból, mennyire felelnek meg a tervezett közönségnek. Ne feledd azt sem, hogy egy műszaki írás kurzuson előnyösebb nem szakértői közönségnek írni — ez sokkal nagyobb kihívást jelent számodra íróként.
Feladatok száma. Hány feladatból áll az az eljárás, amelyről írsz? Használjuk az eljárás kifejezést az utasítások által tárgyalt tevékenységek teljes sorozatára. Egy feladat az eljáráson belüli, részben önálló cselekvések csoportja: például egy mikrohullámú sütő órájának beállítása egy feladat a mikrohullámú sütő használatának teljes eljárásában.
Egy egyszerű eljárás, mint például egy autó olajcseréje, csak egyetlen feladatot tartalmaz; nincsenek részben önálló tevékenységcsoportok. Egy összetettebb eljárás, mint például egy mikrohullámú sütő használata, számos ilyen félfüggetlen feladatot tartalmaz: az óra beállítása, a teljesítményszint beállítása, az időzítő használata, a mikrohullámú sütő tisztítása és karbantartása stb. (A fényképezőgép használatára vonatkozó utasítások feladatok szerint vannak szervezve.)
Egyes utasítások csak egyetlen feladatot tartalmaznak, de azon belül sok lépést. Képzelj el például egy gyerek hintakészlet összeszerelésére vonatkozó utasítást. Saját tapasztalatom szerint több mint 130 lépés volt benne! Ez kissé ijesztő lehet. Jó megközelítés, ha az egymáshoz hasonló és kapcsolódó lépéseket fázisokba csoportosítod, és minden új fázisnál újraszámozod a lépéseket. Egy fázis tehát hasonló lépések csoportja egy egyfeladatos eljáráson belül. A hintakészlet példájában a váz felállítása egy fázis lenne; a szerkezet földhöz rögzítése egy másik; az ülőhinta összeszerelése pedig egy további.
Használj feladatorientált megközelítést. A feladatokra összpontosíts, amelyeket az olvasók el akarnak végezni; a címsorokban használd a „hogyan” vagy az –ás/–és szerkezeteket.
A lépésről lépésre történő ismertetés legjobb megközelítése. Egy másik szempont — amelyet talán nem tudsz azonnal meghatározni — az, hogy mire helyezd a hangsúlyt az utasításaidban. A legtöbb utasítás esetében a feladatokra vagy az eszközökre (illetve azok jellemzőire) összpontosíthatsz.
Egy feladatorientált megközelítés (más néven feladatközpontú szemlélet) esetén, például egy telefonos üzenetrögzítő szolgáltatás használatára vonatkozó utasításoknál, a következő szakaszok szerepelnének:
- üdvözlő üzenet rögzítése
- üzenetek visszajátszása
- üzenetek mentése
- üzenetek továbbítása
- üzenetek törlése stb.
Ezek feladatok — azok a tipikus dolgok, amelyeket a géppel szeretnénk elvégezni. További ismertetésért lásd a feladatelemzésről szóló fejezetet.
Ezzel szemben egy eszközorientált megközelítés esetén, például egy fénymásoló használatára vonatkozó utasításoknál, a következő — meglehetősen valószínűtlen — szakaszok szerepelnének:
- másolás gomb
- megszakítás gomb
- nagyítás/kicsinyítés gomb
- szortírozás/tűzés gomb
- másolatméret gomb stb.
Ha ezen az alapon terveznél egy utasítássort, akkor minden egyes gomb vagy funkció használatához külön lépéseket írnál. Az ilyen eszközorientált megközelítésű utasítások nehezen működtethetők. Előfordulhat, hogy a gomb neve nem teljesen felel meg a hozzá kapcsolódó feladatnak; vagy hogy a feladat elvégzéséhez több gombot kell használni. Ennek ellenére vannak olyan helyzetek, amikor az eszköz-/funkcióközpontú megközelítés előnyösebb lehet.
Feladatcsoportosítások. A feladatok felsorolása önmagában nem mindig elegendő. Előfordulhat, hogy annyi feladat van, hogy azokat csoportosítani kell, hogy az olvasók könnyebben megtalálják az egyes elemeket. Az alábbiak például gyakori feladatcsoportosítások az utasításokban:
- kicsomagolási és beállítási feladatok
- telepítési és testreszabási feladatok
- alapvető működtetési feladatok
- rutinszerű karbantartási feladatok
- hibakeresési feladatok stb.
Az utasítások gyakori szakaszai
Az alábbiak áttekintést adnak azokról a szakaszokról, amelyek gyakran megtalálhatók az utasításokban. Ne feltételezd, hogy mindegyiknek kötelezően szerepelnie kell az általad írt utasításokban, sem azt, hogy pontosan ebben a sorrendben kell megjelenniük, és azt sem, hogy ezek lennének az egyetlen lehetséges szakaszok.
Ahogy az utasítások gyakori szakaszairól olvasol, nézd meg a példa-utasításokat is.
Az utasítások sematikus áttekintése. Ne feledd, hogy ez egy tipikus vagy gyakori modell a tartalomra és a szervezésre — sok más is lehetséges.
Bevezetés. Gondosan tervezd meg az utasításaid bevezetését. Győződj meg róla, hogy elvégzi az alábbi feladatok közül mindazokat (nem feltétlenül ebben a sorrendben), amelyek az adott utasításokra vonatkoznak:
- Megnevezi az ismertetendő konkrét feladatokat vagy eljárást, valamint a lefedettség terjedelmét (mit nem tárgyal).
- Megjelöli, hogy a közönségnek milyen ismeretekre és háttérre van szüksége az utasítások megértéséhez.
- Általános képet ad az eljárásról és arról, mit valósít meg.
- Megjelöli azokat a feltételeket, amikor ezeket az utasításokat használni kell (vagy nem szabad).
- Áttekintést ad az utasítások tartalmáról.
További ismertetésért lásd a bevezetések című szakaszt.
Általános figyelmeztető, óvatossági és veszélyjelzések. Az utasítások gyakran kötelesek figyelmeztetni az olvasókat arra a lehetőségre, hogy tönkretehetik az eszközeiket, elronthatják az eljárást, vagy megsérülhetnek. Az utasítások gyakran hangsúlyoznak kulcspontokat vagy kivételeket is. Ezekben az esetekben speciális figyelmeztetéseket használsz — megjegyzés, figyelmeztetés, óvatosság és veszély jellegű közléseket. Figyeld meg, hogyan használják ezeket a speciális figyelmeztetéseket a fent felsorolt példa-utasításokban.
Műszaki háttér vagy elmélet. Bizonyos típusú utasítások elején (természetesen a bevezetés után) szükség lehet az eljáráshoz kapcsolódó háttér ismertetésére. Egyes utasítások esetében ez a háttér kulcsfontosságú — nélküle az eljárás lépései értelmetlenek lennének. Például előfordulhat, hogy használtál már olyan szoftveres kisalkalmazásokat, amelyekben a piros, zöld és kék csúszkák mozgatásával határozod meg a színeket. Ahhoz, hogy valóban megértsd, mit csinálsz, szükséged van némi színelméleti háttérre. Hasonlóképpen elképzelhető, hogy bizonyos fényképezőgépes utasításokhoz is szükség van némi elméleti ismeretre.
Eszközök és kellékek. Figyeld meg, hogy a legtöbb utasítás tartalmaz egy listát azokról a dolgokról, amelyeket az eljárás megkezdése előtt össze kell gyűjtened. Ez magában foglalja az eszközöket, azokat a szerszámokat, amelyeket az eljárás során használsz (például keverőtálak, kanalak, kenyérsütő formák, kalapácsok, fúrógépek és fűrészek), valamint a kellékeket, azokat a dolgokat, amelyek az eljárás során elfogynak (például fa, festék, olaj, liszt és szögek). Az utasításokban ezeket általában egyszerű függőleges listában vagy kétoszlopos listában sorolják fel. Használd a kétoszlopos listát, ha egyes vagy az összes tételhez specifikációkat kell hozzáadnod — például márkaneveket, méreteket, mennyiségeket, típusokat, modellszámokat stb.
A lépések ismertetése. Amikor eljutsz a lépések tényleges megírásához, több dolgot is szem előtt kell tartanod: (1) a lépések szerkezetét és formátumát, (2) az esetleg szükséges kiegészítő információkat, valamint (3) a nézőpontot és az általános írásstílust.
Szerkezet és formátum. Általában az utasításokat számozott, függőleges listák formájában képzeljük el — és a legtöbb valóban ilyen. Normál esetben a tényleges lépésről lépésre haladó utasításaidat is így formázod. Léteznek azonban eltérések és további megfontolások:
- Fix sorrendű lépések: olyan lépések, amelyeket a bemutatott sorrendben kell végrehajtani. Például egy autó olajcseréjénél az olaj leeresztése kötelezően megelőzi az új olaj betöltését. Ezek számozott listák (általában függőleges számozott listák).
- Változó sorrendű lépések: olyan lépések, amelyeket gyakorlatilag bármilyen sorrendben végre lehet hajtani. Jó példák erre azok a hibakeresési útmutatók, amelyek azt mondják, hogy ellenőrizd ezt, ellenőrizd azt, amikor valamit megpróbálsz megjavítani. Ezeket a lépéseket szinte bármilyen sorrendben elvégezheted. Ennél a típusnál a felsorolásjeles lista a megfelelő formátum.
- Alternatív lépések: olyan esetek, amikor két vagy több módszert mutatnak be ugyanannak a dolognak az elvégzésére. Alternatív lépéseket akkor is használnak, ha különböző feltételek állhatnak fenn. Használj felsorolásjeles listákat ennél a típusnál, az alternatívák közé beszúrva az VAGY szót, vagy olyan bevezető szöveggel, amely jelzi, hogy alternatívák következnek.
- Beágyazott lépések. Egyes esetekben az eljáráson belüli egyes lépések önmagukban is meglehetősen összetettek lehetnek, és al-lépésekre kell bontani őket. Ilyenkor további behúzást alkalmazol, és az al-lépéseket a, b, c stb. sorrendben jelölöd.
- „Lépés nélküli” utasítások. Végül léteznek olyan utasítások is, amelyek valójában nem használhatók számozott, függőleges listákkal, és alig vagy egyáltalán nem tartalmaznak közvetlen, utasító jellegű iránymutatást az olvasó számára. Egyes helyzetek annyira általánosak vagy annyira változatosak, hogy a lépések nem fogalmazhatók meg.
Lásd a listákról szóló fejezetet ezen lehetőségek stílusára és formátumára vonatkozóan.
Kiegészítő magyarázat. Gyakran nem elég egyszerűen megmondani az olvasóknak, hogy ezt vagy azt tegyék. További magyarázó információra van szükségük, például arra, hogyan kell kinéznie az adott dolognak a lépés előtt és után; miért fontos elvégezni ezt a lépést; milyen mechanikai elv áll az adott művelet mögött; vagy akár még részletesebb, mikroszintű magyarázatra a lépésről — az adott lépést alkotó konkrét műveletek ismertetésére.
A kiegészítő magyarázat problémája azonban az, hogy elfedheti magát a tényleges lépést. A tényleges lépésnek — azoknak a konkrét műveleteknek, amelyeket az olvasónak végre kell hajtania — ki kell tűnnie. Nem szabad, hogy egy szöveghalmazba temetve jelenjen meg. Legalább két technika létezik ennek elkerülésére: az utasítást és a kiegészítő magyarázatot külön bekezdésekre lehet bontani; vagy félkövérré lehet tenni magát az utasítást.
A tényleges felhasználói lépések félkövérré tétele az utasításokban. A félkövér szöveg segít megkülönböztetni a tényleges műveletet a kiegészítő információktól.
Kerüld a távirati stílusú írást — az „érthetőnek vett” névelők (a, az, egy) elhagyását. Igaz, a robotok így írnak, de nekünk nem kell.)
Írásstílus. Az utasítások tényleges megfogalmazása, mondatról mondatra, ellentmondásosnak tűnhet ahhoz képest, amit korábbi írásórákon tanítottak. Figyeld meg azonban, hogyan íródnak a „valós életbeli” utasítások — sok felszólító módot (parancsoló, közvetlen megszólítású stílust) használnak, és gyakran szólítják meg közvetlenül az olvasót („te”). Ez teljesen helyénvaló. Fel kell keltened az olvasó figyelmét, teljes mértékben magadra kell vonnod azt. Ezért hangzanak az utasítás stílusú mondatok így: „Most nyomja meg az Előlap Pause gombját a kijelző ideiglenes leállításához” vagy „Ügyeljen arra, hogy ne ...”.
Különös problémát jelent a szenvedő szerkezet használata az utasításokban. Valamilyen furcsa okból egyes utasítások így hangzanak: „A Pause gombot le kell nyomni a kijelző ideiglenes leállításához.” Nemcsak a Pause gomb lelki állapota miatt aggódunk, hanem azon is elgondolkodunk, hogy ki is nyomja meg azt (nekem szólnak?). Vagy vegyük ezt a példát: „Ezután az Időzítő gomb 3:00-ra van állítva.” Olvasóként ezt könnyen félreértheted; azt hiheted, hogy egy meglévő állapotra utal, vagy elgondolkodhatsz: „Ez nekem szól?” Majdnem ilyen rossz a harmadik személy használata is: „A felhasználónak ezután meg kell nyomnia a Pause gombot.” Itt is ugyanaz a bizonytalanság lép fel: körülnézel, és azon tűnődsz: „Én?” (További részletekért lásd a szenvedő szerkezet problémáját.)
Az utasítások írásstílusának egy másik tipikus problémája a névelők elhagyása: „Nyomja meg Pause gombot előlapon kijelző ideiglenes leállításához” vagy „Földlakó, kérem adja meg a legközelebbi pizzéria címét.” Miért tesszük ezt? Titokban mind robotok akarunk lenni? Mindenesetre ügyelj arra, hogy minden névelőt (a, az, egy) és más, normálisan használt szavakat is belefoglalj az utasításokba.
Grafika az utasításokban
Talán minden más írásformánál jobban (talán csak a képregények kivételek), a grafika kulcsfontosságú az utasításokban. Néha a szavak egyszerűen nem képesek megmagyarázni egy lépést. Az illusztrációk gyakran elengedhetetlenek ahhoz, hogy az olvasók vizualizálni tudják, mit kell tenniük.
Egy műszaki írás kurzuson az utasítások megkövetelhetik illusztrációk vagy más grafikai elemek használatát — mindazt, amit az adott utasítások normálisan tartalmaznának. A probléma természetesen az lehet, hogy nem állnak rendelkezésre megfelelő grafikák, vagy hogy nem érzed magad különösebben magabiztosnak művészi képességeidben. Ezek a problémák azonban áthidalhatók! Nézd meg a grafikáról szóló fejezet javaslatait. Ott nemcsak grafikai készítési tanácsokat találsz, hanem a formátumra vonatkozó követelményeket is.
Formátum az utasításokban
Címsorok. Használd tudatosan a címsorokat az utasításaidban. Általában szükség van címsorokra az esetleges háttérszakaszokhoz, a felszerelések és kellékek szakaszához, egy általános címsorra az utasítások részéhez, valamint alcímekre az egyes feladatokhoz vagy fázisokhoz. Nézd meg a fejezet elején található példákat. Lásd a címsorokról szóló részt a gyakori követelményekért.
Listák. Az utasítások általában erősen támaszkodnak listákra, különösen a tényleges lépéseket bemutató számozott függőleges listákra. Az egyszerű függőleges listák vagy a kétoszlopos listák jól működnek a felszerelések és kellékek felsorolásánál. A mondaton belüli listák hasznosak, amikor áttekintést adsz az előttünk álló elemekről. Lásd a listákról szóló részt a gyakori követelményekért.
Különleges figyelmeztetések. Az utasításokban figyelmeztetni kell az olvasókat azokra a helyzetekre, amikor károsíthatják a berendezést, pazarolhatják az anyagokat, az egész eljárás kudarcba fulladhat, vagy saját magukat vagy másokat megsebesíthetik — akár súlyosan vagy halálosan is. Cégek ellen indultak perek az ilyen figyelmeztetések hiánya, rossz megfogalmazása vagy rossz elhelyezése miatt. Lásd a különleges figyelmeztetésekről szóló fejezetet a helyes használatuk, formátumuk és elhelyezésük részletes ismertetéséhez.
Számok, rövidítések és szimbólumok. Az utasítások sok számot, rövidítést és szimbólumot is használnak. Ezekre vonatkozó irányelvekért lásd az adott részt.
Figyelmeztetések behúzása az utasításokban. Az első példában vedd észre, hogy a figyelmeztetés az előző lépés szövegéhez van igazítva. A második példában a súlyos figyelmeztetés az elején szerepel, még a lépések előtt.
AI-parancsok utasításokhoz
Az ellenőrzőlisták, amelyeket általában nem olvasnak el, kisebb módosítással forrásként használhatók AI-parancsokhoz. Másold ki az alábbiakat, illeszd be egy AI-rendszerbe (például a Google Gemini-be), és nézd meg, mit hagyhattál ki.
Megjegyzés: Az alkalmazási levelek tartalmára, formátumára és stílusára vonatkozó összes hivatkozás megtalálható az online műszaki írás tankönyvben.
Amikor AI-t szeretnél használni egy írásprojekt értékelésére, mutatkozz be, mondd el, ki vagy és mit szeretnél. Adj az AI-nak egy referenciapontot az értékeléshez, például egy online tankönyvet. Ezután illeszd be azt, amit az AI-val ellenőriztetni szeretnél.
Igazítsd a bevezetést a saját személyazonosságodhoz.