In dit hoofdstuk, boekontwerp betekent de inhoud, stijl, formaat, ontwerp en volgorde van de verschillende typische componenten van een boek. "Componenten" verwijst hier naar de daadwerkelijke secties of pagina's van een boek, zoals de editie-opmerking, de inleiding, de index, of de voorkant of achterkant van de omslag. In de pagina-ontwerp hoofdstuk, de term element verwijst naar dingen die praktisch overal in een boek meerdere keren kunnen voorkomen, zoals koppen, voetteksten, tabellen, illustraties, lijsten, mededelingen, markeringen, enzovoort.

Het volgende biedt een overzicht van de typische componenten van een gedrukt technisch boek en de typische inhoud, indeling, stijl en volgorde van die componenten. Zeker, geen enkele gebruikershandleiding, technisch referentiemanual, snelreferentiedocument of ander dergelijk document zou eigenlijk al deze componenten zo ontworpen en in de juiste volgorde hebben zoals je nu gaat lezen. In plaats daarvan zal deze review een overzicht geven van de mogelijkheden—laten we zeggen het scala aan mogelijkheden.

Opmerking: Momenteel hebben we alleen een voorbeeld gebruikershandleiding ontwikkeld in FrameMaker en vervolgens geëxporteerd naar PDF. Het mist een woordenlijst, maar alle andere onderdelen van een typische gebruikershandleiding zijn aanwezig. (Ik kan die "d" in "Filepad" niet achterhalen!) Houd er rekening mee dat het niet voldoet aan enkele van de font- en margespecificaties die hieronder zijn vermeld.

Voordat je begint met het lezen van het volgende, pak een aantal hardware- en softwareboeken zodat je hun inhoud, stijl, format en volgorde kunt vergelijken met wat hier wordt besproken.

Voor nog meer details dan je hier ziet, raadpleeg deze twee standaardbranchebronnen:

Je kunt voorbeelden van deze boekcomponenten zien in Techdoc Ontwerp.

Voor- en achterkant omslagen

Productdocumenten voor betalende klanten hebben meestal mooi ontworpen voorhoezen, ook al is de inhoud van het boek van een lagere kwaliteit. Op de voorzijde zie je doorgaans enkele of alle van de volgende elementen:

Het kan een uitdaging zijn om een goed formaat te vinden voor de bedrijfsnaam, productnaam en boektitel. Soms kan dit oplopen tot een hele alinea tekst! Bedrijven zijn het erover verdeeld of ze versies en releases op de vooronderwerpen moeten aangeven—sommigen doen dat; sommigen doen dat niet. Bijna altijd zie je echter het platform aangegeven—of het product nu voor de Macintosh, de pc, UNIX, enzovoort is.

De achterkant van harde gebruikersgidsen en handleidingen is meestal heel eenvoudig. Typisch bevat het het boek bestelnummer, de naam van het bedrijf met de bijbehorende merk symbolen, een copyright symbool en tekst over het eigendom van het boek, en een verklaring over in welk land het boek is gedrukt. Je zult ook streepjescodes op de achterkant vinden. Kijk of jouw software een streepjescodes kan genereren—je hoeft alleen de streepjescodes utility te openen en het boek bestelnummer in te typen, en de utility genereert de streepjescodes.

Titelpagina

De titelpagina is doorgaans een duplicaat van de voorcover, maar met bepaalde elementen weggelaten. Gewoonlijk weggelaten zijn de afbeeldingen, bedrijfs- of productlogo's en slogans. Sommige technische publicaties laten de titelpagina helemaal weg vanwege de schijnbaar overbodige duplicatie. (En bij een oplage van 20.000 exemplaren betekent een enkele pagina veel!)

Editienotitie

De editie-opmerking is meestal de eerste instantie van reguliere tekst in een technische publicatie, hoewel het meestal in kleinere letters is. Het bevindt zich op de achterkant van de titelpagina. Als de technische uitgever de lean-and-green aanpak volgt en de titelpagina elimineert, zal de editie-opmerking op de achterkant van de voorkant verschijnen.

Niemand houdt ervan om de kleine lettertjes te lezen, maar kijk eens naar de verklaringen die meestal in een uitgavebericht zijn opgenomen:

Afwijzingen

Zie de sectie over editieaankondigingen, waar disclaimers meestal weggestopt zijn. Als een product of de publicatie ervan een hele aparte pagina nodig heeft voor de disclaimers, koop ik het niet!

Merken

Hoewel veel bedrijven hun eigen en andere bedrijven' handelsmerken vermelden in de uitgave kennisgeving, sommigen geven de voorkeur aan het vermelden op een aparte pagina, direct na de editie kennisgeving. Deze plaatsingsbeslissingen zijn bijna strikt het domein van bedrijfsadvocaten; als schrijver moet je misschien voldoen, ongeacht hoe slecht de beslissing is qua boekontwerp of schrijfstijl. Vergeet niet dat je alleen die geregistreerde productnamen vermeldt die in dat specifieke boek voorkomen.

Je zult merken dat sommige publicaties extreme maatregelen nemen met handelsmerken: ze asterisk of voetnoten de eerste, of zelfs elke vermelding van een geregistreerde productnaam. Maar opnieuw, dit zijn richtlijnen van bedrijfslawyers waaraan technische schrijvers zich helaas moeten onderwerpen.

Garantiestellingen

Meer juridische zaken. Dit zijn de "garanties" die het bedrijf zal bieden met betrekking tot zijn product. Soms worden deze gepubliceerd in de voorzijde van het boek; maar, meer gepast vanuit een boekontwerperstandpunt, worden ze op een aparte kaart gedrukt en ingesloten in de shrinkwrap van het boek of het product. Nogmaals, net als bij editiemeldingen, is dit tekst die je simpelweg als "standaardtekst" meeneemt en op de juiste plek in het boek plaatst.

U moet er echter voor zorgen dat bedrijven soms meerdere versies van editie-meldingen, veiligheidsmeldingen, garanties, communicatieverklaringen en dergelijke onderhouden. Als schrijver moet u ervoor zorgen dat u de juiste versie gebruikt (en, door erachter te komen welke correct is, krijgt u de kans om veel nieuwe mensen in het bedrijf te ontmoeten!). En wat u ook doet, verander de tekst van deze standaarditems niet, hoe slecht ze ook geschreven zijn. Wijzigingen moeten doorgaans goedgekeurd worden door de bedrijfsadvocaten (die dit meestal met tegenzin doen en alleen na veel inspanningen van uw kant en nadat er veel tijd is verstreken).

Veiligheidsmededelingen

Hardwareproducten hebben doorgaans een sectie met veiligheidswaarschuwingen aan het begin van hun boeken. Deze kunnen bijvoorbeeld als een subsectie van de inleiding voorkomen, of als een aparte sectie op zichzelf. Deze secties brengen doorgaans alle gevaren-, waarschuwing- en voorzichtigheidswaarschuwingen samen die door het boek heen voorkomen en rangschikken ze op een logische manier. Maar zelfs met deze voorafgaande waarschuwing plaatsen hardwareboeken nog steeds de individuele waarschuwingen op de plekken waar ze van toepassing zijn. (Voor meer informatie, zie speciale mededelingen.)

Communicatieverklaringen

Hardwareboeken vereisen ook communicatieverklaringen zoals voorgeschreven door de regeringen van de landen waaraan deze producten worden verzonden. In de VS vereist de FCC bepaalde communicatieverklaringen, afhankelijk van de "klasse" van het hardwareproduct. Als schrijver moet je ervoor zorgen dat je de juiste communicatieverklaring gebruikt voor het product dat je documenteert—en de verklaring op geen enkele manier bewerken (heilige wettelijke woorden!).

Inhoudsopgave

De inhoudsopgave (TOC) bevat doorgaans minstens een tweede niveau van detail (de kop 1's in de werkelijke tekst) zodat lezers preciezer kunnen vinden wat ze nodig hebben. Schrijvers, redacteuren en boekontwerpers discussiëren meestal over de volgorde van de TOC. Wat gebruiksvriendelijkheid betreft, is het veel beter om de TOC zo dicht mogelijk bij de voorkant van het boek te hebben, zo niet helemaal aan het begin van het boek. Wat betreft juridische zaken maken mensen zich echter zorgen dat al die communicatiestaten, garanties, auteursrechten, handelsmerken en veiligheidswaarschuwingen eerst moeten komen. In die gevallen waar gebruiksvriendelijkheid de overhand heeft, gebruiken boeken elke tactiek die ze kunnen om dit juridische materiaal uit de voorpagina te krijgen: garanties worden op aparte kaarten gezet en met het boek of product samengeperst; garanties, communicatiestaten, handelsmerken en dergelijke kunnen in bijlagen worden gedumpt.

Problemen met het maken van een mooi geformatteerde inhoudsopgave? Zie Maak een professionele inhoudsopgave.

Lijst van figuren

Technische handleidingen voor gewone gebruikers hebben typisch geen lijsten van figuren. In feite hebben de figuren zelf meestal geen volledige figuurtitels. Maar dit wil niet zeggen dat een lijst van figuren geen plaats heeft in technische handleidingen. Het hangt allemaal af van de lezer en de behoeften van de lezer—en de inhoud van het boek. Als het boek tabellen, illustraties, diagrammen, grafieken en andere elementen bevat die lezers direct willen terugvinden, is een figurenlijst op zijn plaats.

Voorwoord

De functie van het voorwoord is om lezers klaar te stomen om het boek te lezen. Dit doet het door:

In traditionele boekuitgeverij komt de inleiding vóór de inhoudsopgave; maar zoals eerder besproken in de inhoudsopgave sectie, technische publicatiedeskundigen willen dat de inhoudsopgave eerder in het boek verschijnt omwille van gebruiksvriendelijkheid.

Lichaamshoofdstukken

Oh ja, en er is echte tekst in deze boeken—het is niet allemaal voorwoord! Weinig anders te zeggen hier dan dat de meeste technische boeken hoofdstukken of secties hebben, en in sommige gevallen delen. Zie het hoofdstuk over pagina ontwerp voor opmaak, stijl en ontwerpproblemen voor elementen zoals kopteksten, voetteksten, koppen, lijsten, meldingen, tabellen, graphics, kruisverwijzingen en markering.

Bijlagen

Zoals je weet, zijn appendixes voor materiaal dat gewoon niet lijkt te passen in het hoofddeel van een boek, maar niet uit het boek kan worden weggelaten. Appendixes zijn vaak de plek voor grote onhandige tabellen. Sommige technische publicaties hebben dingen zoals garanties in de appendixes. Wat betreft het formaat is een appendix net als een hoofdstuk—behalve dat het "Appendix A" of iets dergelijks heet, en de kop- en voetteksten overeenkomen met die andere nummering en naamgevingsconventie (A-1, A-2, enzovoort voor pagina's in Appendix A).

Woordenlijst

Sommige technische publicaties bevatten een sectie met gespecialiseerde termen en hun definities. Merk op dat de meeste glossaria een lay-out met twee kolommen gebruiken. Typisch vormt elke term en zijn definitie een aparte alinea, waarbij de term in kleine letters staat (tenzij het een eigennaam is) en vetgedrukt is, gevolgd door een punt, daarna de definitie in reguliere romeinse tekst. Merk ook op dat definities meestal geen volledige zinnen zijn. Goede glosser definities moeten de techniek van formele-zinsdefinities gebruiken zoals beschreven in de definitie hoofdstuk van deze online tekst. Meerdere definities worden meestal aangeduid met Arabische cijfers tussen haakjes. Glossarium-paragrafen bevatten ook Zie verwijzingen naar voorkeurstermen en Zie ook verwijzingen naar gerelateerde termen.

Index

Indexen zijn doorgaans ook twee-koloms en bevatten ook Zie verwijzingen naar voorkeurstermen en Zie ook verwijzingen naar gerelateerde termen. Zie het hoofdstuk over indexering voor processen en richtlijnen voor het maken van goede indexen.

Lezer-respons formulier

Voor de opkomst van het internet en sociale media bevatten sommige technische publicaties een papieren formulier waarmee lezers opmerkingen, vragen en evaluaties van het boek konden opsturen. Uiteraard blijkt dat deze formulieren vaker klachten oproepen over defecte functies in het product dat het boek documenteert. Met de opkomst van het internet zijn deze formulieren online gegaan, en boeken verwijzen simpelweg naar hun locatie online.

Boekontwerp en lay-out

Typisch zijn gebruikershandleidingen en manuals die door hardware- en softwarefabrikanten worden geproduceerd, ontworpen op een vrij austere en spartanische manier. Hightechbedrijven ontwikkelen soms elke negen maanden nieuwe versies en releases van hun product. In deze context is een verfijnd ontwerp gewoon niet praktisch. Hier zijn enkele typische lay-out- en ontwerpelementen die je zult zien:

Opmerking: Dit sluit de discussie over het fysieke boek af. componenten. Om dit overzicht van het ontwerp van gedrukte boeken te voltooien, zie het hoofdstuk over paginastructuur, dat dekt elementen zoals kop- en voetteksten, koppen, lijsten, bijzondere mededelingen, tabellen, graphics, markering, kruisverwijzingen, en meer.

Ik zou graag je gedachten, reacties en kritiek over dit hoofdstuk waarderen: je reactie.