- Ez a fejezet, valamint a Műszaki ▒~Mrás teljes tankönyve, a műszaki írás készségeire összpp ontosít.
- Az itt található műszaki tartalom sikeressége, pontossága vagy id▒~Qszerűsége nem garantált.
- Az oldalon található képekben lév▒~Q szöveg fordítása a lehet▒~Q leghamarabb elkészül.
- Kattintson ide, hogy segítsen David McMurrey webtárhelyének költségeit fedezni: Adományozzon bármii lyen összeget! Az Online Technical Writing továbbra is ingyenes marad.
Kérjük, kattintson ide, hogy segítsen. Dávid McMurrey webtárhely kifizetése:
Adományozz bármilyen kis összeget, amennyit csak tudsz!
Az Online műszaki írás ingyenes marad.
Technikai dokumentumok (beleértve a kézikönyveket, a fehér könyveket és az útmutatókat) szerkezete az iparágtól, a szakmától vagy a szervezettől függően különböző lehet. Ez a fejezet egy hagyományos szerkezetet mutat be. Ha technikai írással kapcsolatos kurzust veszel, győződj meg róla, hogy a fejezetben bemutatott szerkezet elfogadható. Ugyanez igaz arra az esetre is, ha tudományos, üzleti vagy kormányzati kontextusban írsz technikai dokumentumot.
A NotebookLM által generált infografika erről a fejezetről
Megjegyzés: Évekig ez az online műszaki írással foglalkozó tankönyv általánosan úgy hivatkozott a jelentésekre, hogy gyakorlatilag bármi, ami műszaki információt tartalmaz. De mivel a „jelentés” egy konkrét műfajra utal a műszaki dokumentumok között, a generikus elnevezést „techdoc”-ra kellett megváltoztatni, amely a műszaki dokumentum rövidítése.
Techdocs (a műszaki dokumentumok gyűjtőneve) rendelkeznek specifikációkkal, akárcsak bármely más típusú projekt. A műszaki dokumentumokra vonatkozó specifikációk magukban foglalják az elrendezést, a szervezést és a tartalmat, a címsorok és listák formátumát, a grafikai elemek tervezését és így tovább. A kötelező szerkezetnek és formátumnak az az előnye a műszaki dokumentumoknál, hogy te vagy bárki más elvárhatja, hogy ismerős módon legyenek megtervezve—tudod, mit keress és hol keresd. A műszaki dokumentumokat általában sietve olvassák—az emberek sietnek, hogy hozzáférjenek a szükséges információhoz, a kulcsfontosságú tényekhez, a következtetésekhez és egyéb lényeges elemekhez. Egy szabványos műszaki dokumentum-formátum olyan, mint egy ismerős környék.
Amikor elemezed egy technikai dokumentum felépítését, figyeld meg, mennyire ismétlődnek bizonyos szakaszok. Ez a duplikáció arra vezethető vissza, hogyan olvassák az emberek a technikai dokumentumokat. Nem olvassák végig őket egyben: előfordulhat, hogy a vezetői összefoglalóval kezdik, ugrálnak a részek között, és valószínűleg nem olvasnak el minden oldalt. A kihívásod az, hogy úgy tervezz technikai dokumentumokat, hogy ezek az olvasók találkozzanak a kulcsfontosságú tényekkel és következtetésekkel, függetlenül attól, hogy a dokumentumból mennyit olvasnak el, vagy milyen sorrendben teszik azt.
Mindenképpen nézd meg a példa technikai dokumentáció.
A tipikus műszaki jelentés szabványos összetevőit ebben a fejezetben tárgyaljuk. A következő szakaszok végigvezetik Önt ezeknek az összetevőknek mindegyikén, kiemelve a kulcsfontosságú jellemzőket. Ahogy olvassa és alkalmazza ezeket az iránymutatásokat, ne feledje, hogy ezek iránymutatások, nem parancsok. Különböző cégeknek, szakmáknak és szervezeteknek megvannak a maguk, eltérő iránymutatásai a műszaki dokumentumokra vonatkozóan — Önnek alkalmazkodnia kell a gyakorlatát ezekhez is, valamint az itt bemutatottakhoz.
Kísérő üzenet
A kísérő üzenet vagy kísérőlevél (vagy feljegyzés), vagy e-mail. A nyomtatott levél (vagy feljegyzés) vagy csatolva van a műszaki dokumentum külsejéhez egy gemkapoccsal, vagy a műszaki dokumentumba van bekötve. Az e-mail tartalmaz egy hivatkozást a műszaki dokumentumra, vagy maga a műszaki dokumentum van csatolva. Ez egy kommunikáció ön—a műszaki dokumentum írója—részéről a címzettnek, annak a személynek, aki kérte a műszaki dokumentumot és aki akár fizethet is önnek a szakértői konzultációért. Lényegében azt mondja: „Rendben, itt a műszaki dokumentum, amelyet megbeszéltük, hogy ilyen-olyan határidőre elkészítek. Röviden: ez és az található benne, de nem tér ki erre meg arra. Kérem, tudassa velem, megfelel-e az igényeinek.” A kísérő üzenet elmagyarázza a kontextust—azokat az eseményeket, amelyek a műszaki dokumentum létrejöttét előidézték. Tartalmaz olyan információkat a műszaki dokumentumról, amelyek nem tartoznak a műszaki dokumentumba.
Példák egy átadási levélre és egy átadási üzenetre.
A kísérőlevél példájában figyelje meg a szabványos üzleti levélformátumot. Ha belső technikai dokumentumot ír, ehelyett használja a memorandum formátumot; mindkét esetben a tartalom és a szerkezet ugyanaz:
Első bekezdés. Megemlíti a technikai dokumentum nevét, dőlt betűkkel formázva. Azt is megemlíti, hogy mikor kötötték meg a technikai dokumentum megírására vonatkozó megállapodást.
Középső bekezdés. A technikai dokumentáció céljára összpontosít, és rövid áttekintést nyújt annak tartalmáról.
Utolsó bekezdés. Arra ösztönzi az olvasót, hogy vegye fel a kapcsolatot, ha kérdései, megjegyzései vagy aggályai vannak. Jóindulattal zárul, kifejezve azt a reményt, hogy az olvasó kielégítőnek találja a műszaki dokumentációt.
Ahogy egy technikai dokumentum bármely más eleménél, előfordulhat, hogy ennek az üzenetnek (vagy feljegyzésnek) a tartalmát is módosítanod kell konkrét helyzetekhez igazítva. Például hozzáadhatsz egy további bekezdést, amely felsorolja azokat a kérdéseket, amelyeket szeretnéd, hogy az olvasók fontolóra vegyenek, amikor áttekintik a technikai dokumentumot.
Borítók, címoldal és címke
Ha a technikai dokumentációja több mint tíz oldalas, kösse be valamilyen módon, és készítsen címkét a borítóra.
Borítók
A borítók szilárd, professzionális megjelenést és védelmet biztosítanak a technikai dokumentáció számára. Számos borító típus közül választhatsz. Tartsd szem előtt ezeket a tippeket:
- Teljesen elfogadhatatlanok az átlátszó (vagy színes) műanyag toktípusok, amelyeknél a műanyag hüvely a bal szélén van. Olyanok, mintha egy elsőéves angolóráról valók lennének; ráadásul bosszantó a használatuk—az olvasóknak küzdeniük kell, hogy nyitva tartsák őket, és bajlódniuk kell az általuk keltett sztatikus elektromossággal.
- Kisebb mértékben elfogadhatók azok a borítók, amelyeknél kilyukasztják az oldalakat, felfűzik azokat, és lehajlítják a papírrögzítő csapokat. Ha ezt a típust használja, hagyjon a bal szélen további fél hüvelykes margót, hogy az olvasóknak ne kelljen szétfeszíteniük az oldalakat. Természetesen ez a borítótípus megakadályozza, hogy az oldalak laposan feküdjenek: az olvasóknak meg kell ragadniuk a rendelkezésre álló tárgyakat vagy különféle testrészeket kell használniuk az oldalak lesúlyozásához.
- Messze a legjobb borítók azok, amelyek lehetővé teszik, hogy a műszaki dokumentumok maguktól nyitva maradjanak (lásd a következő rész illusztrációját). Milyen nagy megkönnyebbülés, ha egy műszaki dokumentum az ölünkben vagy az asztalunkon nyitva fekve marad. Ez a típus műanyag spirált használ a kötéshez és vastag kartonpapírt a borítókhoz. Érdeklődjön a helyi fénymásoló üzletnél az ilyen típusú kötésekről; olcsók, és növelik a munkája professzionális megjelenését. A következőkben látható egy szimulált példa a műanyag spirálkötésre.
Általában kevésbé előnyösek a lyukasztott lapokból álló jegyzetfüzetek vagy a gyűrűs mappák. Ezek túl terjedelmesek a rövid műszaki dokumentumokhoz, és a laplyukak hajlamosak elszakadni. Természetesen a gyűrűs mappa megkönnyíti a lapok cseréjét; ha így fogják használni a műszaki dokumentumot, akkor jó választás. A „magasabb kategóriában” a túl díszes borítók vannak, műbőr hatású megjelenéssel és aranyszínű díszítéssel. Kerüld őket—tartsd egyszerűnek, letisztultnak és funkcionálisnak.
Címlap
A legegyszerűbb formájában a techdoc címe a borítón szereplő szöveg másolata—esetleg néhány részlettel kiegészítve.
Nézze meg a címlapot. Kivonat és vezetői összefoglaló.
Címkék
Mindenképp gondoskodj arról, hogy találj ki egy címkét a technikai dokumentumod borítójára. Ez egy lépés, amelyet egyes technikai dokumentumírók elfelejtenek. Címke nélkül a technikai dokumentum névtelen lesz; figyelmen kívül hagyják.
A legjobb módja egy címke létrehozásának az, ha a szövegszerkesztő programmal megtervezel egyet egy szabványos oldalon, a címke információit körülvevő grafikus kerettel. Nyomtasd ki, majd menj el egy fénymásolóüzletbe, és másoltasd rá közvetlenül a műszaki dokumentum borítójára.
A címkére nem kerül sok minden: a műszaki dokumentum címe, az Ön neve, az Ön szervezetének neve, egy műszaki dokumentum-nyomonkövetési szám és egy dátum. A címkére vonatkozóan nincsenek szabványos követelmények, bár az Ön cége vagy szervezete rendelkeznie kell a saját követelményeivel. (Az alábbiakban egy műszaki dokumentum-címke példája látható.)
Kísérőlevél és műszaki dokumentáció borítója (borítócímkével).
Kivonat és Vezetői Összefoglaló
A legtöbb műszaki techdoc legalább egy kivonatot—néha kettőt tartalmaz, ebben az esetben a kivonatok különböző szerepeket töltenek be. A kivonatok összefoglalják egy techdoc tartalmát, de a különböző típusok ezt különböző módon teszik:
- Leíró összefoglaló. Ez a típus áttekintést nyújt a technikai dokumentum céljáról és tartalmáról. Néhány technikai dokumentum kialakításában a leíró kivonatot a címlap aljára helyezik, ahogyan az alábbiakban látható:
Leíró összefoglaló. Hagyományosan a címlapon helyezik el (nem a borítólapon). - Vezetői összefoglaló. Egy másik gyakori típus a végrehajtói összefoglaló, amely szintén összegzi a műszaki dokumentumban található legfontosabb tényeket és következtetéseket. Lásd az alábbi példát. Olyan, mintha sárga kiemelővel jelölte volna meg a műszaki dokumentum kulcsmondatait, majd mindet külön oldalra gyűjtötte volna össze, és olvashatóság szempontjából szerkesztette volna őket. Általában a végrehajtói összefoglalók a tíz–ötven oldalas műszaki dokumentumok hosszának egytizedétől egyhuszadáig terjednek. Hosszabb, ötven oldalnál hosszabb műszaki dokumentumok esetén a végrehajtói összefoglaló nem haladhatja meg a két oldalt. A végrehajtói összefoglaló célja, hogy röviden összefoglalja a műszaki dokumentumot — olyasmit, amit gyorsan el lehet olvasni.
Ha a vezetői összefoglaló, a bevezetés és a kísérőüzenet ismétlődőnek tűnik, ne feledje, hogy az olvasók nem feltétlenül a technikai dokumentum elejétől kezdik és nem lapoznak végig oldalról oldalra. Átlapoznak: előfordulhat, hogy csak a tartalomjegyzéket nézik át; általában átfutják a vezetői összefoglalót a kulcsfontosságú tények és következtetések miatt. Lehet, hogy a dokumentum törzséből csak egy-két szakaszt olvasnak el figyelmesen, majd a többit kihagyják. Emiatt a technikai dokumentumokat úgy tervezik, hogy legyen bennük némi ismétlődés, így az olvasók biztosan látni fogják a fontos információkat, bárhol is nyúlnak bele a dokumentumba.
Tartalomjegyzék (mi kerül először), majd a vezetői összefoglaló.
Tartalomjegyzék
Bármely tartalomjegyzék (TOC) formátumot is használ, ezek a közös szabványok:
- Csak a kezdő oldalszám. Bár néhány automatikus tartalomjegyzék-generátor megjeleníti az oldalszámtartományt, a szabvány szerint csak az első oldalszámot kell feltüntetni.
- Tartalmazandó címsorszintek. Ahogy a fenti tartalomjegyzék mutatja, jelenítse meg a címsorok felső két szintjét, kivéve, ha a technikai dokumentációnak sok alfejezete van. A tartalomjegyzéknek egy pillantásra alkalmas módot kell biztosítania az információk gyors megtalálásához.
- Térköz és nagybetűhasználat. Figyeld meg, hogy a fent látható TOC szöveges elemei behúzottak. Az első szintű címek teljes egészében NAGYBETŰSEKBŐL állnak; a második szintű címek minden fő szó kezdőbetűjét nagybetűvel írják; a harmadik szintű címek mondatstílusú nagybetűzést alkalmaznak.
- Függőleges térköz. Figyelje meg, hogy az első szintű szakaszok fölött és alatt extra hely van, ami növeli az olvashatóságot.
- A techdoc minden oldala (a borító első és hátsó lapját kivéve) számozott; de néhány oldalon a számok nem jelennek meg.
- A kortárs kialakításban a dokumentum minden oldalán arab számokat használnak; a hagyományos kialakításban a bevezetés előtti összes oldal (a dokumentum törzsének első oldala) kis római számokat használ.
- A speciális oldalakon, például a címlapon és a bevezető első oldalán, az oldalszámok nem jelennek meg.
- Az oldalszámok a lap több lehetséges területére helyezhetők. Általában a legjobb és legegyszerűbb választás az, ha az oldalszámokat a lap alján, középre helyezzük (ne felejtsük el elrejteni őket a különleges oldalakon).
- Ha az oldalszámokat az oldal tetejére helyezi, el kell rejtenie őket a fejezet- vagy szakasznyitókon, ahol a címsor vagy cím az oldal tetején található.
- Tartalmazza a műszaki dokumentum (jelentés) a következőket (megfelelően formázva) ebben a sorrendben: kísérőlevél; címlap; tartalomjegyzék; ábrák, táblázatok vagy mindkettő listája; bevezetés; törzsrészek (fejezetek); függelékek (szükség szerint); információforrások; hátsó borító (ha szükséges)? Részletekért lásd: Műszaki dokumentáció tervezése.
- Bár lehet találékony és játékos, vajon a technikai dokumentum címe megfelelően jelzi a témáját? Részletekért lásd: Techdoc címek.
- Ha a tartalomjegyzék és az ábrák jegyzéke (illetve a táblázatoké) vezető pontokat használ, az oldalszámok jobbra igazítottak? Ha a tartalomjegyzék és az ábrák jegyzéke (illetve a táblázatoké) az oldal jobb szélén tünteti fel az oldalszámokat, használnak-e vezető pontokat? Részletekért lásd Tartalomjegyzékek és az ábrák (táblázatok) jegyzéke.
- Jelzi-e a bevezető megfelelően a műszaki dokumentum témáját, célját és a célközönségét? Tartalmazza-e a bevezető a tárgyalandó alfejezetek listáját és egy jelzést a terjedelemről (mi nincs benne)? Részletekért lásd Bemutatkozások.
- Tartalmaz-e ez a műszaki dokumentáció megfelelő részleteket, konkrétumokat, példákat—bármit, ami szükséges az állítások és az általánosságok magyarázatához?
- Figyelembe véve a témát, a célt és a közönséget, hiányzik‑e bármilyen létfontosságú tartalom ebből a műszaki dokumentációból? Vannak‑e szükségtelen tartalmak? Vannak‑e információk ebben a műszaki dokumentációban, amelyek technikailag helytelenek? Hiányzik‑e bármilyen kritikus műszaki információ?
- Tartalmazza ez a technikai dokumentáció bármilyen nyilvánvalóan átvett információt, amely nincs semmilyen módon dokumentálva?
- A hivatkozások (az információforrások listájában szereplő tételekre utaló hivatkozások) a techdoc törzsében az APA-, az MLA- vagy a módosított IEEE-stílus szerint jelennek meg? Az információforrások listájában szereplő tételek APA-, MLA- vagy módosított IEEE-stílus szerint vannak-e formázva? Részletekért lásd Dokumentáció: kölcsönvett információforrások.
- Tartalmaznak-e az összes táblázat és nem díszítő célú ábra leíró címet (feliratot) és forrást (ha szükséges)? Részletekért lásd: Táblázatcímek.
- Minden táblázat és nem díszítő jellegű ábra a hozzájuk kapcsolódó szöveghez a lehető legközelebb található?
- Előfordulnak-e rövid, magyarázó kereszthivatkozások a táblázatok és a nem dekoratív ábrák előtt? A részletekért lásd: Magyarázó kereszthivatkozások.
- Használják a technikai dokumentáció törzsében a címsorok és alcímsorok szabványos formátumát? Részletekért lásd: Címsorok.
- A technikai dokumentáció fő részei (fejezetei) új oldalon kezdődnek-e a nyomtatott változatokban?
- Számozott, függőleges listákat használnak-e olyan listaelemek esetében, amelyeknek kötött sorrendjük van? Felsorolásjelekkel ellátott, függőleges listákat használnak-e olyan listaelemek esetében, amelyeknek nincs kötött sorrendjük? Használják-e a bevezető mondatokat minden lista előtt? Részletekért lásd: Függőleges listák.
- A közvetlen idézetek forrása fel van tüntetve, és a forrástüntetések helyesen vannak-e írásjelekkel ellátva? Minden közvetlen idézet, összegzés és parafrázis megfelelően van-e hivatkozva az APA-, MLA- vagy módosított IEEE-stílus szerint? Részletekért lásd: Idézetek és hivatkozások.
- Mentes a techdoc szövege nyelvtani, nyelvhasználati és írásjelezési hibáktól? Részletekért lásd: Gyakori nyelvtani, nyelvhasználati és helyesírási problémák.
- Mentes a techdoc szövege a bőbeszédűségtől és egyéb mondatstílusbeli hibáktól? Részletekért lásd: Szószátyárság, egyéb mondatstílusbeli problémák.
- Megértheti-e ezt a műszaki dokumentumot a célközönsége (amint azt az átadási üzenet és a bevezetés jelzi)? Részletekért lásd Közönség-elemzés, és nézd meg A műszaki szöveg fordítása.
- MI, hogy befejezd a technikai dokumentációm értékelését, adj egy numerikus osztályzatot 100 és 55 között.
Kitöltőpontok és jobbra igazított oldalszámok. A hagyományos tartalomjegyzékhez, amely vezetőpontokat és jobbra igazított oldalszámokat használ:
Jobbra igazítás. Ebben a példában, vegye figyelembe, hogy a vezetőpontok „kivezetik” a jobbra igazított oldalszámokat.
Pontozott kitöltő karakterek és jobbra igazított oldalszámok.
Ez a tartalomjegyzék tizedes számozási stílust használ a fejezet- és szakaszszámokhoz, ami gyakori a műszaki dokumentációkban. A könyv más részei csak a legfelső szintű fejezeteknél a nagybetűs római számok stílusát használják (lásd ).
Nehézségei vannak egy szépen formázott tartalomjegyzék létrehozásával? Lásd Készítsen professzionális megjelenésű tartalomjegyzéket.
Vesszők és oldalszámok. Ha nem kötelező a vezetőpont (leader-dot) formátum, és inkább elkerülné, használhatja ezt a széles körben elfogadott formátumot:
|
3. AZ ENERGIAHATÉKONYSÁG KULCSELVEI, 5
Passzív tervezési stratégiák, 6
4. SZABVÁNYOK ÉS TANÚSÍTVÁNYOK, 11Aktív energia rendszerek, 7 Megújuló energiaforrások integrációja, 9
LEED, 11
Energy Star, 12 Élő Épület Kihívás, 14 |
Ábrák és táblázatok jegyzéke
Az ábrák jegyzékének sok olyan tervezési megfontolása van, amely megegyezik a tartalomjegyzékével. Az olvasók az ábrák jegyzékét használják, hogy megtalálják a műszaki dokumentumod illusztrációit, diagramjait, táblázatait és grafikonjait.
Problémák adódnak, ha egyszerre vannak táblázatok és ábrák. Szigorúan véve az ábrák illusztrációk, rajzok, fényképek, grafikonok és diagramok. A táblázatok a szavakból és számokból álló sorok és oszlopok; nem minősülnek ábráknak.
Hosszabb műszaki dokumentációk esetén, amelyek egyenként tucatnyi ábrát és táblázatot tartalmaznak, készítsen külön listákat az ábrákról és a táblázatokról. Helyezze őket ugyanarra az oldalra, ha elférnek, amint az az alábbi ábrán látható. A két listát egyesítheti „Ábrák és táblázatok listája” címszó alatt, és az elemeket az alábbi illusztráción látható módon ábraként vagy táblázatként azonosíthatja.
Bevezetés
Egy technikai dokumentum egyik alapvető eleme a bevezetője—Győződjön meg róla, hogy tisztában van annak valódi céljával és tartalmával. Egy technikai dokumentumban a bevezető felkészíti az olvasót a technikai dokumentum fő részének elolvasására. Lásd Bemutatkozások a bevezetők írásáról szóló megbeszéléshez.
Íme egy példa a bevezetőre:
Ábrák és táblázatok listája, majd a bevezetés.
Ha nincsenek táblázatok, legyen az „Ábrák jegyzéke”. Egy műszaki írás kurzuson kérdezze meg az oktatóját, hogy kötelező-e a címsorok tizedes számozási stílusa.
A műszaki dokumentum törzse
A technikai dokumentáció törzse természetesen magát a főszöveget jelenti, vagyis azokat a szakaszokat, amelyek a bevezető és a záró rész között találhatók. Az alább illusztráltak mintapéldalakat mutatnak be.
Címsorok
Minden, kivéve a legrövidebb technikai dokumentumok esetében (két oldal vagy kevesebb), használj címsorokat a tárgyalt különböző témák és al-témák elkülönítésére. A címsorok lehetővé teszik az olvasók számára, hogy átfussák a technikai dokumentumot, és gyorsan azokra a részekre ugorjanak, ahol az általuk keresett információ található. Lásd címsorok a címsorokra vonatkozó irányelvekért.
Felsorolások és számozott listák
A technikai dokumentum törzsében használjon megfelelő helyeken felsorolásjelekkel ellátott, számozott és kétoszlopos listákat is. A listák segítenek a főbb pontok kiemelésében, megkönnyítik az információ követését, és megtörik a szöveg egységes, fal-szerű tömbjét. Lásd listák a listákra vonatkozó iránymutatásokért.
Szimbólumok, számok és rövidítések
A műszaki megbeszélések általában sok szimbólumot, számot és rövidítést tartalmaznak. Ne feledje, hogy a számok és a szavak használatára vonatkozó szabályok a műszaki világban eltérnek. A régi szabály, miszerint minden tíznél kisebb számot ki kell írni, nem mindig érvényes a műszaki dokumentációkban. (Lásd számok kontra szavak az irányelvekért.)
Kivéve a technikai dokumentum törzsét.
Egy műszaki szövegírási kurzuson kérdezd meg az oktatódat, hogy a címsorok tizedes számozási stílusa kötelező-e. Továbbá egy másik dokumentációs rendszer is előírható—nem az IEEE, amely a mérnököknek szól.
Grafikák és ábracímek
Műszaki dokumentumokban valószínűleg szükséged lesz rajzokra, ábrákra, táblázatokra és diagramokra. Ezek nemcsak bizonyos típusú információk hatékonyabb közlésére alkalmasak, hanem a műszaki dokumentációdnak is professzionálisabb és tekintélyesebb megjelenést kölcsönöznek. Ha még soha nem helyeztél ilyen jellegű grafikákat egy dokumentumba, vannak viszonylag egyszerű módszerek erre—nem kell profi grafikusnak lenned. A grafikák s-hez való hozzáadásának stratégiáiért lásd grafika. Az s-hez táblák hozzáadására vonatkozó stratégiákért lásd asztalok.
Kereszthivatkozások
Előfordulhat, hogy az olvasókat a techdoson belül található szorosan kapcsolódó információkra, vagy más, releváns információkat tartalmazó forrásokra kell irányítanod. Ezeket nevezik keresztutalások. Például ráirányíthatják az olvasókat egy mechanizmus tárgyalásától annak illusztrációjához. Átirányíthatják az olvasókat egy függelékhez, ahol egy témával kapcsolatos háttéranyag található (olyan háttér, ami egyszerűen nem fér bele a szövegbe). És irányíthatják az olvasókat a techdocodon kívülre más információ—cikkekhez, techdocokhoz és könyvekhez, amelyek a tiéddel kapcsolatos információkat tartalmaznak. Amikor kereszthivatkozásokat hozol létre, kövesd az alábbiakban bemutatott irányelveket kereszthivatkozások.
Következtetések
A legtöbb technikai dokumentációhoz szükséges, hogy tartalmazzon egy záró szakaszt. Amikor megtervezed a technikai dokumentációd záró szakaszát, gondold át, milyen funkciókat tölthet be a dokumentum többi részéhez viszonyítva. A záró szakaszokra vonatkozó ötletek a következőkben találhatók. következtetések.
Függelékek
A függelékek azok a kiegészítő részek, amelyek a következtetés után következnek. Mit helyezel a függelékekbe?—minden, ami nem fér el kényelmesen a technikai dokumentáció fő részében, de nem hagyható ki teljesen a dokumentumból. A függeléket általában nagy adattáblákhoz, nagyméretű mintakód-részletekhez, kihajtható térképekhez, olyan háttéranyagokhoz használják, amelyek túl alapvetőek vagy túl előrehaladottak a technikai dokumentáció törzséhez képest, illetve olyan nagy illusztrációkhoz, amelyek egyszerűen nem férnek el a törzsben. Minden, amit túlságosan nagynak érzel a technikai dokumentáció fő részéhez, vagy amelyről úgy gondolod, hogy zavaró lenne és megszakítaná a dokumentum folyását, jó jelölt a függelékbe helyezésre. Megjegyzendő, hogy mindegyiket betűvel jelölik (A, B, C és így tovább).
Információforrások
A források dokumentálása arról szól, hogy felépítsd, fenntartsd és megvédd a hitelességedet a szakmában. Fel kell tüntetned ("dokumentálnod kell") a kölcsönvett információkat, függetlenül attól, milyen alakban vagy formában adod elő azokat. Akár szó szerint idézed, parafrazálod vagy összefoglalod—az még mindig kölcsönvett információ. Akár könyvből, cikkből, diagramról, táblázatból, weboldalról, termékismertetőről vagy egy olyan szakértőtől származik, akit személyesen kérdezel meg—az még mindig kölcsönvett információ.
A dokumentációs rendszerek a szakemberektől és a szakterületektől függően változnak. A mérnökök az IEEE rendszert használják, melynek példái végig megtalálhatók ebben a fejezetben. Egy másik gyakran használt dokumentációs rendszert az Amerikai Pszichológiai Társaság (APA) biztosít. Lásd dokumentáció Részletekért.
Oldalszámozás
A hagyományos technikai dokumentáció tervezésében alkalmazott oldalszámozási stílus elsősorban abban különbözik a kortárs technikai dokumentáció tervezéstől, hogy az előbbi a bevezető előtti részeken (minden, ami a bevezető előtt van) kis római számokat használ.
Megjegyzés: Hosszabb műszaki dokumentációk gyakran a fejezetenkénti oldalszámozási stílust alkalmazzák, amelyet folió per fejezetnek vagy kettős számozásnak neveznek (például a 2. fejezet oldalai 2-1, 2-2, 2-3, és így tovább számozást kapnának). Hasonlóképpen, a táblázatok és az ábrák is ezt a számozási stílust alkalmaznák. Ez a stílus megkönnyíti az oldalak hozzáadásának és törlésének folyamatát.
MI-promptok technikai dokumentációhoz
Ellenőrző listák, amelyeket általában nem olvasnak el, némi módosítással forrásként használhatók AI-promptokhoz. Másold a következőt, illeszd be egy olyan AI-rendszerbe, mint a Google Gemini, és nézd meg, mit hagyhattál ki.
Megjegyzés: Minden utalás a jelentkezési levelek tartalmára, formátumára, stílusára vagy azok alkotóelemeire megtalálható a online műszaki írás tankönyv.
|
AI-parancsok technikai dokumentációhoz Ha azt szeretnéd, hogy az MI értékelje az írási projektedet, mutatkozz be, mondd el az MI-nek, hogy ki vagy és mit szeretnél. Adj az MI-nek egy hivatkozási pontot az értékelésekhez, például egy online tankönyvet. Aztán tedd közzé, mit szeretnél, hogy a Gemini ellenőrizzen az értékelésében. Íme egy példa: Helló, MI. David McMurrey vagyok, az Austin Community College (Austin, Texas) kiberbiztonsági hallgatója. Kérem, hogy a következő műszaki dokumentumot ezzel értékelje. online tankönyv és a következő kérdések: |
Kapcsolódó információk
Tartalomjegyzék: Az olvasók kulcsfontosságú szervezési eszköze
Értékelném a gondolataidat, reakcióidat és kritikáidat ezzel a fejezettel kapcsolatban: a válaszod—David McMurrey.
