- Ang kabanatang ito, pati na rin ang natitirang bahagi ng aklat sa Teknikal na Pagsulat, ay nakatuon sa mga kasanayan sa teknikal na pagsulat. Ang teknikal na nilalaman dito ay hindi ginagarantiyahan na magiging matagumpay, tumpak o napapanahon.
- Ang kabanatang ito ay naisalin gamit ang Open AI ChatGPT. Mangyaring iulat ang mga problema sa wika sa admin@mcmassociates.io.
- Isasalin ang teksto sa mga larawan sa pahinang ito sa lalong madaling panahon.
- Pindutin dito upang tulungan si David McMurrey na magbayad para sa web hosting: Mag-donate ng kahit anong halaga! Mananatiling libre ang Online Technical Writing.
Sa kabanatang ito, disenyo ng libro nangangahulugang ang nilalaman, istilo, pormat, disenyo, at pagkakasunod-sunod ng iba't ibang karaniwang bahagi ng isang aklat. "Mga bahagi" rito ay tumutukoy sa mga aktwal na seksyon o pahina ng isang aklat tulad ng paunawa ng edisyon, paunang salita, indeks, o ang pabalat sa harap o likod. Sa Kabanata sa Disenyo ng Pahina, ang termino elemento tumutukoy ito sa mga bagay na maaaring mangyari nang maraming beses halos kahit saan sa isang libro, tulad ng mga ulo ng pahina, mga paanan ng pahina, mga talahanayan, mga ilustrasyon, mga listahan, mga paunawa, mga pagtatampok, at iba pa.
Ang sumusunod ay nagbibigay ng pangkalahatang-ideya ng mga tipikal na bahagi ng isang nakalimbag na teknikal na aklat at ng karaniwang nilalaman, pormat, estilo, at pagkakasunod-sunod ng mga bahaging iyon. Tiyak na walang isang solong gabay ng gumagamit, teknikal na manwal ng sanggunian, dokumentong mabilisang sanggunian, o iba pang katulad na dokumento ang talagang magkakaroon ng lahat ng mga bahaging ito na idinisenyo at inayos nang eksaktong sa paraang mababasa mo ngayon. Sa halip, ang pagsusuring ito ay magbibigay ng isang pangkalahatang-ideya ng mga posibilidad—sabihin nating ang saklaw ng mga posibilidad.
Tandaan: Sa kasalukuyan, mayroon lamang kaming halimbawa Gabay ng Gumagamit Binuo sa FrameMaker at pagkatapos ay inilabas bilang PDF. Wala itong glosaryo, ngunit ang lahat ng iba pang bahagi ng isang tipikal na gabay ng gumagamit ay naroroon. (Hindi ko maintindihan ang "d" sa "Filepad"!) Tandaan na hindi nito ginagamit ang ilan sa mga kinakailangan sa font at margin na nakalista sa ibaba.
Bago ka magsimulang basahin ang mga sumusunod, kumuha ng ilang mga libro tungkol sa hardware at software upang maaari mong ihambing ang kanilang nilalaman, estilo, format, at pagkakasunod-sunod sa mga tinalakay dito.
Para sa mas detalyadong impormasyon kaysa nakikita mo rito, sumangguni sa dalawang karaniwang sanggunian ng industriya na ito:
- Teknikal na mga publikasyon ng Sun. Basahin Mo Muna! Anumang kamakailang edisyon. Prentice Hall.
- Microsoft Korporasyon. Manwal ng Estilo ng Microsoft para sa Mga Teknikal na Publikasyon. Anumang kamakailang edisyon. Microsoft Press.
Makikita mo ang mga halimbawa ng mga bahaging ito ng aklat sa Disenyo ng Dokumentasyong Teknikal.
Harap at likod ng pabalat
Karaniwan, ang mga dokumento ng produkto para sa mga nagbabayad na customer ay may maganda at maayos na disenyo ng harapang pabalat, kahit na sa loob ay mababa ang kalidad ng aklat. Sa harapang pabalat, karaniwan mong makikita ang ilan o lahat ng sumusunod:
- Pangalan ng kumpanya
- Pangalan ng produkto
- Plataporma ng produkto o sistema ng pagpapatakbo
- Mga bersyon ng produkto at mga numero ng paglabas
- Pamagat ng aklat
- Mga logo ng kumpanya o produkto
- Mga simbolo ng tatak-pangkalakal
- Likhang-sining
- Numero ng order ng libro
- Slogan ng kumpanya o produkto
Maaaring maging mahirap alamin ang magandang format para sa pangalan ng kumpanya, pangalan ng produkto, at pamagat ng libro. Minsan, maaari itong umabot hanggang sa isang buong talata ng teksto! Hati ang mga kumpanya kung dapat bang ilagay ang mga numero ng bersyon at release sa mga pabalat—ang ilan ay ginagawa; ang ilan ay hindi. Halos palagi, gayunpaman, makikita mong nakasaad ang plataporma—kung ang produkto ay para sa Macintosh, PC, UNIX, at iba pa.
Karaniwang napakasimple ang likurang pabalat ng mga hardcopy na gabay ng gumagamit at mga manwal. Kadalasan, naglalaman ito ng numero ng order ng aklat, ang pangalan ng kumpanya na may angkop na mga simbolo ng trademark, isang simbolo ng copyright at pahayag tungkol sa pagmamay-ari ng aklat, at isang pahayag kung saang bansa ipinag-imprenta ang aklat. Makakakita ka rin ng mga bar code sa likurang pabalat. Tingnan kung kayang mag-generate ng bar code—kailangan mo lang i-access ang bar code utility at i-type ang numero ng order ng aklat, at gagawa ng bar code ang utility.
Pahina ng Pamagat
Karaniwang kopya ng harapang pabalat ang pahina ng pamagat, ngunit may ilang elemento na tinatanggal. Karaniwang tinatanggal ang mga likhang sining, mga logo ng kumpanya o produkto, at mga slogan. May ilang teknikal na publikasyon na inaalis nang buo ang pahina ng pamagat dahil sa tila hindi kailangang pag-uulit. (At sa isang print run na 20,000 kopya, malaking bagay ang isang pahina!)
Paunawa sa Edisyon
Ang paunawa ng edisyon ay karaniwang ang unang halimbawa ng regular na teksto sa isang teknikal na publikasyon, bagaman karaniwan itong nasa mas maliit na tipo. Matatagpuan ito sa likod ng pahina ng pamagat. Kung ang teknikal na nagpapalathala ay gumagamit ng mapagtipid at pangkalikasang pamamaraan at tinatanggal ang pahina ng pamagat, lilitaw ang paunawa ng edisyon sa likod ng harapang pabalat.
Walang gustong magbasa ng maliliit na letra, ngunit tingnan ang mga pahayag na karaniwang nakapaloob sa isang paunawa ng edisyon:
- Petsa ng publikasyon— Kasama hindi lamang ang taon kundi kung minsan pati ang buwan kung kailan inilathala ang libro.
- Bilang ng edisyon—Kung ang libro ay unang, ikalawang, o ikatlong edisyon.
- Aplikabilidad ng produkto—Karaniwang ipinapahiwatig ng paunawa ng edisyon kung aling plataporma, bersyon, at numero ng paglabas ng produkto ang naaangkop sa aklat.
- Buong pamagat ng aklat—Ipinapakita sa italiko.
- Mga paunawa—Nakakagulat, inaangkin ng mga gumagawa ng produkto na hindi nila ginagarantiyahan na ang libro ay teknikal na tama, kumpleto, o walang problema sa pagsulat, o na ang produkto ay walang maliliit na depekto, o na ito ay tumutugon sa pangangailangan ng mamimili. Makakakita ka rin ng karagdagang mga disclaimer bukod pa rito.
- Simbolo ng karapatang-sipi at pahayag—Makikita mo ang simbolong bilog-C ng copyright at isang pahayag na nagbabala sa mga mambabasa na huwag kopyahin ang aklat nang walang pahintulot.
- Mga pahintulot sa karapatang-ari—Ang mundo ng mataas na teknolohiya ay madalas kumilos nang napakabilis, kaya sa halip na lumikha ng kanilang sariling bersyon ng isang bahagi ng produkto at ng katumbas nitong dokumentasyon, ang mga kumpanya ay simpleng bumibili ng code o disenyo at pati na rin ng mga karapatan na muling iimprinta ang dokumentasyon. Karaniwang nangangahulugan ito ng pagkilala sa copyright sa paunawa ng edisyon (bagaman kung maraming hiniram na materyal, kailangang maging malikhain ang mga nagpapalathala sa paglalagay ng lahat ng mga pagkilalang ito).
- Mga tugon ng mga mambabasa—Kung minsan, ang paunawa ng edisyon ay magsasama ng ilang paghihikayat sa mga kostumer na makipag-ugnayan sa kumpanya tungkol sa mga alalahanin sa produkto o dokumentasyon. Minsan ay nakalakip sa paunawa ng edisyon ang mga tagubilin kung paano makikipag-ugnayan sa kumpanya. Kadalasan din na nakapaloob ang isang medyo di-magalang pahayag na ang anumang komunikasyon ng kostumer ay nagiging pag-aari ng kumpanya.
- Mga tatak-pangkalakal—Ang ilang teknikal na publikasyon ay naglilista ng mga kilalang tatak sa paunawa ng edisyon. Kasama rito ang parehong mga tatak ng kumpanya at ang mga tatak ng ibang mga kumpanya na binanggit sa aklat. Dahil sa pagdami ng mga bagong produkto sa mundo ng mataas na teknolohiya, at dahil na rin sa pagdami ng mga tatak, ang ilang mga publikasyon ay halos sumusuko at naglalagay ng isang simpleng pahayag na ang anumang mga sanggunian sa mga pangalan ng produktong may tatak ay pagmamay-ari ng kani-kanilang mga kumpanya.
Mga paunawa
Tingnan ang seksyon tungkol sa mga paunawa ng edisyon, kung saan karaniwang nakatago ang mga paunawa. Kung ang isang produkto o ang publikasyon nito ay nangangailangan ng isang buong hiwalay na pahina para sa mga paunawa nito, hindi ko ito bibilhin!
Mga tatak-pangkalakal
Bagaman maraming kumpanya ay inililista ang kanilang sariling mga tatak-pangkalakal at ang mga tatak-pangkalakal ng ibang mga kumpanya sa Paunawa ng edisyon, ang ilan ay mas gusto na ilista ang mga ito sa isang hiwalay na pahina, kaagad pagkatapos ng paunawa ng edisyon. Halos mahigpit na nasasakupan ng mga abogado ng kumpanya ang mga desisyong ito tungkol sa paglalagay; bilang isang manunulat, maaaring kailanganin mong sumunod kahit gaano pa man hindi maganda ang desisyon pagdating sa disenyo ng libro o istilo ng pagsulat. Tandaan, ililista mo lamang ang mga pangalan ng produktong may rehistradong tatak na lumalabas sa partikular na aklat na iyon.
Mapapansin mo na ang ilang publikasyon ay gumagawa ng labis na hakbang pagdating sa mga trademark: nilalagyan nila ng asterisk o tala sa paa ang unang paglitaw, o kahit ang bawat paglitaw ng pangalan ng produktong may trademark. Ngunit muli, ito ay mga direktiba ng mga abogado ng kumpanya na kailangang tanggapin ng mga teknikal na manunulat, gaano man ito kalungkot.
Mga Garantiya
Higit pang mga usaping legal. Ito ang mga "garantiya" na susuportahan ng kumpanya hinggil sa kaniyang produkto. Minsan inilalathala ang mga ito sa paunang bahagi ng libro; subalit, mas naaangkop mula sa pananaw ng disenyo ng libro, karaniwan itong nililimbag sa isang hiwalay na kard at isinisingit sa loob ng pambalot na plastik ng libro o produkto. Muli, tulad ng sa mga paunawa ng edisyon, ito ay teksto na simpleng idinadagdag bilang "karaniwang teksto" at inilalagay sa tamang lugar sa loob ng libro.
Gayunpaman, dapat mong malaman na ang mga kumpanya minsan ay nagpapanatili ng maraming bersyon ng mga paunawa sa edisyon, mga paunawa sa kaligtasan, mga garantiya, mga pahayag sa komunikasyon at iba pa. Bilang isang manunulat, dapat mong tiyakin na ginagamit mo ang tamang bersyon (at, sa pagtukoy kung alin ang tama, magkakaroon ka ng pagkakataon na lumabas at makilala ang maraming bagong tao sa loob ng kumpanya!). At anuman ang iyong gawin, huwag baguhin ang teksto ng mga paunang nakahandang pahayag na ito, gaano man kahila‑hilakbot ang pagkakasulat nila. Kadalasan ang mga pagbabago ay kailangang aprubahan ng mga abogado ng kumpanya (na karaniwang gumagawa nito nang may pag‑aatubili at tanging pagkatapos ng maraming pagsisikap mula sa iyo at pagkaraan ng mahabang panahon).
Mga Paunawa sa Kaligtasan
Karaniwang may seksyon ng mga paunawa sa kaligtasan ang mga produktong hardware sa unahan ng kanilang mga libro. Maaaring lumitaw ang mga ito bilang isang subseksyon ng panimula, halimbawa, o bilang isang hiwalay na seksyon mismo. Karaniwan, pinagsasama ng mga seksyong ito ang lahat ng mga paunawa ng panganib, babala, at pag-iingat na matatagpuan sa buong libro at inaayos ang mga ito sa isang lohikal na paraan. Ngunit kahit na may ganoong paunang babala, inilalagay pa rin ng mga aklat ng hardware ang mga indibidwal na paunawa sa mga puntong naaangkop ang mga ito. (Para sa karagdagang impormasyon, tingnan Mga Espesyal na Paunawa.)
Mga pahayag sa komunikasyon
Kinakailangan din ng mga manwal ng hardware ng mga pahayag ukol sa komunikasyon ayon sa itinakda ng mga pamahalaan ng mga bansang pinadadalhan ng mga produktong ito. Sa Estados Unidos, ang FCC ay nangangailangan ng ilang pahayag ukol sa komunikasyon depende sa "klase" ng produktong hardware. Bilang isang manunulat, dapat kang mag-ingat na gamitin ang tamang pahayag ng komunikasyon para sa produktong iyong idodokumento — at huwag baguhin ang pahayag sa anumang paraan (mga banal na salitang legal!).
Talaan ng mga nilalaman
Ang talaan ng nilalaman (TOC) karaniwang naglalaman ng hindi bababa sa ikalawang antas ng detalye (ang mga pamagat na antas 1 sa aktwal na teksto) upang mas tiyak na mahanap ng mga mambabasa ang kanilang kailangan. Karaniwan, pinagtatalunan ng mga manunulat, editor, at taga-disenyo ng libro ang pagkakasunod-sunod ng talaan ng nilalaman. Sa aspeto ng kakayahang magamit, mas mabuti na ilagay ang talaan ng nilalaman nang pinakamalapit sa unahan ng libro hangga't maaari, kung hindi man mismo sa pinaka-unahan ng libro. Sa usapin ng mga legalidad, gayunpaman, nag-aalala ang mga tao na ang lahat ng mga pahayag ng komunikasyon, mga garantiya, mga karapatang-ari, mga tatak-pangkalakal, at mga paunawa sa kaligtasan ay dapat mauuna. Sa mga lugar na nangingibabaw ang kakayahang magamit, gumagamit ang mga libro ng lahat ng taktika na kanilang makakaya upang mailabas ang ganitong mga materyal na ligal mula sa paunang bahagi: inilalagay ang mga garantiya sa hiwalay na mga card at sinelyuhan sa plastik kasama ng libro o produkto; ang mga garantiya, mga pahayag ng komunikasyon, mga tatak-pangkalakal at iba pang katulad nito ay maaaring ilagay sa mga apendiks.
Nahihirapan ka bang gumawa ng maayos na naka-format na talaan ng nilalaman (TOC)? Tingnan Gumawa ng propesyonal na Talaan ng Nilalaman.
Talaan ng mga pigura
Karaniwang walang mga listahan ng mga pigura sa mga teknikal na manwal para sa karaniwang mga gumagamit. Sa katunayan, kadalasan ang mga pigura mismo ay walang ganap na pamagat. Ngunit hindi nito ibig sabihin na walang lugar ang isang listahan ng mga pigura sa mga teknikal na manwal. Nakasalalay ito sa mambabasa at sa mga pangangailangan ng mambabasa—at pati na rin sa nilalaman ng aklat. Kung ang aklat ay naglalaman ng mga talahanayan, ilustrasyon, tsart, grap, at iba pa na nais direktang hanapin ng mga mambabasa, ang listahan ng mga pigura ay angkop.
Paunang salita
Ang tungkulin ng paunang salita ay ihanda ang mga mambabasa na basahin ang aklat. Ginagawa ito sa pamamagitan ng:
- Paglalarawan sa nilalaman at layunin ng libro
- pagtukoy o kahit maikling paglalarawan sa produktong sinusuportahan ng libro
- Ipinapaliwanag ang uri ng mambabasa kung kanino nakalaan ang aklat.
- Nagbabalangkas ng mga pangunahing nilalaman ng aklat.
- na nagpapakita ng anumang espesyal na kumbensiyon o terminolohiyang ginamit sa aklat
- pagbibigay ng mga numero ng suporta at marketing, at iba pa
Sa tradisyonal na paglalathala ng mga aklat, nauuna ang paunang salita sa talaan ng mga nilalaman; ngunit tulad ng naunang tinalakay sa Talaan ng Nilalaman Sa seksyon, gusto ng mga nasa teknikal na paglalathala na mailagay nang mas maaga ang Talaan ng Nilalaman (TOC) sa libro para sa mga kadahilanang may kinalaman sa pagiging madaling gamitin.
Mga kabanata ng katawan
Oo, at may tunay na teksto sa mga aklat na ito—hindi lahat ay paunang bahagi! Wala nang masyadong masasabi dito maliban sa karamihan ng mga teknikal na aklat ay may mga kabanata o seksyon, at sa ilang mga kaso, mga bahagi. Tingnan ang kabanata tungkol sa disenyo ng pahina para sa mga isyu sa format, estilo, at disenyo para sa mga elemento tulad ng mga header, mga footer, mga pamagat, mga listahan, mga paunawa, mga talahanayan, mga grapiko, mga cross-reference, at pagbibigay-diin.
Mga Apendiks
Tulad ng alam mo, ang mga apendiks ay para sa mga materyal na tila hindi umangkop sa pangunahing bahagi ng isang aklat ngunit hindi rin maaaring tanggalin mula sa aklat. Madalas na inilalagay sa mga apendiks ang malalaki at hindi madaling ayusin na mga talahanayan. Ang ilang teknikal na publikasyon ay may mga bagay tulad ng mga garantiya sa mga apendiks. Sa usapin ng format, ang isang apendiks ay halos katulad lamang ng isang kabanata, maliban na tinatawag ito na "Apendiks A" o katulad nito, at ang mga header at footer ay tumutugma sa ibang sistema ng pag-numero at pag-pangalan (A-1, A-2, at iba pa para sa mga pahina sa Apendiks A).
Talahulugan
Ang ilang teknikal na publikasyon ay naglalaman ng seksiyon ng mga espesyalisadong termino at ang kanilang mga kahulugan. Pansinin na karamihan sa mga glosaryo ay gumagamit ng layout na may dalawang kolum. Karaniwan, ang bawat termino at ang kahulugan nito ay bumubuo ng hiwalay na talata, kung saan ang termino ay nakasulat sa maliit na titik (maliban kung ito ay pangalang pantangi) at naka-bold, sinundan ng tuldok, at pagkatapos ay ang kahulugan sa karaniwang roman. Pansinin din na ang mga kahulugan ay karaniwang hindi kumpletong mga pangungusap. Dapat gumamit ang magagandang depinisyon ng glosaryo ng teknik ng pormal-na-pangungusap na depinisyon tulad ng inilalarawan sa Kabanata ng Depinisyon ng tekstong online na ito. Karaniwang tinutukoy ang maramihang mga depinisyon gamit ang mga arabikong numero sa panaklong. Naglalaman din ang mga talata ng glosaryo ng Tingnan mga sanggunian sa mga pinapaborang termino at Tingnan din mga sanggunian sa mga kaugnay na termino.
Indeks
Karaniwan ding dalawang-kolum ang mga indeks at naglalaman din ng Tingnan mga sanggunian sa mga ginustong termino at Tingnan din Mga sanggunian sa mga kaugnay na termino. Tingnan ang kabanata tungkol sa pagtatala para sa mga proseso at mga patnubay sa paglikha ng mahusay na mga indeks.
Formularyo ng Tugon ng Mambabasa
Bago sumikat ang Internet at social media, ang ilang teknikal na publikasyon ay may kasamang hardcopy na porma upang payagan ang mga mambabasa na magpadala ng mga komento, tanong, at pagsusuri ng aklat. Siyempre, lumalabas na mas madalas na nakakakuha ang mga pormang ito ng mga reklamo tungkol sa depektibong paggana ng produktong idinedokumento ng aklat. Sa pag-usbong ng Internet, lumipat na online ang mga pormang ito, at ang mga aklat ay simpleng nagtuturo na lamang kung nasaan ang mga ito sa internet.
Disenyo at ayos ng libro
Karaniwan, ang mga gabay ng gumagamit at mga manwal na ginawa ng mga tagagawa ng hardware at software ay dinisenyo sa medyo mahigpit at payak na paraan. Ang mga kumpanyang high-tech ay bumubuo ng mga bagong bersyon at pagpapalabas ng kanilang produkto minsan tuwing siyam na buwan. Sa ganitong konteksto, ang sopistikadong disenyo ay hindi praktikal. Narito ang ilan sa mga karaniwang tampok ng layout at disenyo na makikita mo:
- Ang sukat ng pahina ay kadalasang tinutukoy ng mga konsiderasyon sa pag-iimpake pati na rin ng mga karaniwang sukat ng pahina na inaalok ng mga kumpanya ng pag-iimprenta. Kapag ang sukat ng pahina ay hindi isang limitasyon, ang ilang kumpanya ay gagamit ng sukat ng pahina na 8.5 × 11-pulgada—ito ay nagpapadali nang malaki sa produksyon para sa mga manunulat.
- Karaniwang idinisenyo ang mga pahina upang magkahalili bilang kanang at kaliwang pahina. Ang footer para sa kaliwang (pantay) pahina ay nagsisimula sa numero ng pahina at nagtatapos sa pamagat ng aklat. Ang footer para sa kanang (hindi pantay) pahina ay nagsisimula sa pamagat ng kabanata at nagtatapos sa numero ng pahina.
- Magkahalo ang mga gawi kung ang paglalagay ng mga numero ng pahina ay tuloy-tuloy sa buong libro o pa-kabanata.
- Maliban kung medyo maliit ang mga pahina, karaniwan sa mga teknikal na manwal ang nakalawit na disenyo ng mga pamagat kaugnay ng mga pahina. Karaniwang isang pulgada hanggang isa't kalahating pulgada ang nakalawit na indent.
- Karaniwan, 12-point Times New Roman ang mga font para sa pangunahing teksto at Arial para sa mga pamagat. Ginagamit ang karaniwang pagitan ng linya at ng espasyo sa pagitan ng mga salita. Tingnan ang kabanata tungkol sa pagbibigay-diin para sa iba pang mga isyu sa tipograpiya.
- Medyo karaniwan ang mga margin, isa hanggang dalawang pulgada sa lahat ng gilid. Karaniwan, isang karagdagang kalahating pulgada ang ginagamit sa panloob na mga margin para sa pagbubuklod.
- Kadalasan, ang kulay ay hindi ginagamit sa mga manwal at gabay na ito, karaniwang dahil sa mga konsiderasyong pang-gastos at pang-kahusayan.
Tandaan: Dito nagtatapos ang talakayan tungkol sa nakalimbag na aklat. mga bahagi. Upang kumpletuhin ang pangkalahatang-ideya ng disenyo ng mga nalimbag na aklat, tingnan ang kabanata tungkol sa disenyo ng pahina, na sumasaklaw sa mga elemento tulad ng mga header at footer, mga pamagat, mga listahan, mga espesyal na paalala, mga talahanayan, mga grapiko, pagbibigay-diin, mga sanggunian na magkaka-ugnay, at marami pa.
Magpapasalamat ako sa iyong mga saloobin, reaksyon, at kritika tungkol sa kabanatang ito: ang iyong tugon.
