Klik hier om te helpen David McMurrey betaal voor webhosting:
Doneer elk klein bedrag dat je kunt.
Online technisch schrijven blijft gratis.
Deze pagina is in reparatie.
Een gebruikershandleiding is een technisch document dat uitlegt hoe een gebruiker van een product veelvoorkomende taken kan uitvoeren. Veelvoorkomend taken zijn de acties die de gebruiker in staat moet zijn om uit te voeren. De gebruiker is op een niveau van kennis en ervaring bedoeld door het product. Sommige producten hebben basisgebruikers en ervaren gebruikers—een gebruikershandleiding kan aan een van die behoeften of beide voldoen. Denk aan een magnetron: het kan een basisgebruiker hebben, en dat is zo'n beetje alles. Aan de andere kant kan een grafisch ontwerpproduct zowel basisgebruikers als ervaren gebruikers hebben.
NotebookLLM-gegenerateerde infographic van dit hoofdstuk
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 uitgeversmelding, het voorwoord, de index, of de voor- of achterkant. In de pagina-ontwerp hoofdstuk, de term element verwijst naar dingen die meerdere keren praktisch overal in een boek kunnen voorkomen, zoals kopteksten, 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, het formaat, de stijl en de volgorde van die componenten. Zeker, geen enkele gebruikershandleiding, technisch referentiehandboek, snelreferentiedocument of ander dergelijk document zal eigenlijk al deze componenten precies zo ontworpen en geordend hebben als je gaat lezen. In plaats daarvan geeft deze review een overzicht 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!) Wees je ervan bewust dat het niet voldoet aan enkele van de font- en margerequirements die hieronder zijn vermeld.
Voordat je begint met het lezen van het volgende, pak een aantal boeken over hardware en software zodat je hun inhoud, stijl, formaat en volgorde kunt vergelijken met wat hier wordt besproken.
Voor nog meer details dan je hier ziet, raadpleeg deze twee standaard branchebronnen:
- Sun Technische Publicaties. Lees Me Eerst! Elke recente editie. Prentice Hall.
- Microsoft Corporation. Microsoft Handleiding voor Stijl voor Technische Publicaties. Elke recente uitgave. Microsoft Press.
Je kunt voorbeelden van deze boekcomponenten zien in Techdoc Ontwerp.
Voor- en achteromslag
Productdocumenten voor betalende klanten hebben meestal fraai ontworpen omslagen, zelfs als de inhoud van het boek van lage kwaliteit is. Op de omslag zie je meestal een of meer van de volgende dingen:
- Bedrijfsnaam
- Productnaam
- Productplatform of besturingssysteem
- Productversie en releasenummers
- Boektitel
- Bedrijf of productlogo's
- Merken symbolen
- Kunstwerk
- Boek bestelnummer
- Bedrijfs- of product slagzin
Het kan een uitdaging zijn om een goed formaat te bedenken voor de bedrijfsnaam, productnaam en boektitel. Soms kan dit oplopen tot een hele paragraaf tekst! Bedrijven zijn nogal verdeeld over het al dan niet aangeven van versie- en release-nummers op de voorzijde—sommigen doen dat; sommigen doen dat niet. Bijna altijd zie je echter dat het platform wordt aangegeven—of het product nu voor de Macintosh, de pc, UNIX, enzovoort is.
Voorbeeld van een omslagpagina.
De achterkant van harde gebruikershandleidingen en manuals is meestal heel eenvoudig. Typisch bevat het het boek bestelnummer, de naam van het bedrijf met bijbehorende merk symbolen, een copyright symbool en een tekst over het eigendom van het boek, en een verklaring over in welk land het boek is gedrukt. Je vindt ook barcodes op de achterkant. Kijk of je software een barcode kan genereren—je hoeft alleen maar de barcode utility te openen en het boek bestelnummer in te typen, en de utility genereert de barcode.
Titelpagina
De titelpagina is meestal een duplicaat van de voorkant, 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 onnodige duplicatie. (En bij een oplage van 20.000 exemplaren betekent een enkele pagina veel!)
Voorbeeld van een titelpagina.
Uitgavebericht
De editieaankondiging is doorgaans de eerste instantie van reguliere tekst in een technische publicatie, hoewel deze meestal in kleinere lettergrootte is. Het verschijnt op de achterkant van de titelpagina. Als de technische uitgever de lean-and-green aanpak hanteert en de titelpagina elimineert, verschijnt de editieaankondiging op de achterkant van de voorkaft.
Niemand houdt ervan om de kleine lettertjes te lezen, maar kijk eens naar de zaken die meestal in een editiebericht zijn opgenomen:
Voorbeeld van een editie-notificatie
Merken
Of het al dan niet vermelden van handelsmerken en hoe je dat doet, is de verantwoordelijkheid van bedrijfsadvocaten. In ieder geval vermeld je alleen die handelsmerk-productnamen die in die specifieke gebruikershandleiding voorkomen.
Merken worden het meest vaak aangeduid:
- in de editie opmerking (zoals de bovenstaande illustratie toont)
- in een aparte sectie ergens in de gebruikershandleiding
vermeld die opmerking
Als bedrijfsadvocaten willen dat elke vermelding van een merknaam wordt aangegeven met een asterisk of voetnoot, probeer ze dan te overtuigen van die ontwerpfiasco van de pagina. Het bederven van tekst met asterisken of voetnootnummers is afleidend voor lezers.
Garanties
Garanties zijn van toepassing op fysieke hardwareproducten—niet op software. Bedrijfsjuristen nemen de verantwoordelijkheid voor de garantieformulering en -indeling. Als je een voorbeeldgebruikershandleiding of boek voor je portfolio aan het maken bent, kun je dit anonieme "garantievoorbeeld" gebruiken.pop-up om aan te tonen dat u zich ervan bewust bent dat garanties inbegrepen moeten zijn.
softwaregaranties?Veiligheidsinformatie
Hardwareproducten hebben doorgaans een sectie met veiligheidswaarschuwingen aan het begin van hun boeken. Deze kunnen bijvoorbeeld als een subsectie van het voorwoord voorkomen, of als een aparte sectie op zichzelf. Deze secties verzamelen doorgaans alle gevaren-, waarschuwing- en voorzichtigheidswaarschuwingen die door het boek heen voorkomen en ordenen deze op een bepaalde 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.)
Communicatiestatementen
Hardwareboeken vereisen ook communicatiestaten zoals voorgeschreven door de regeringen van de landen waartoe deze producten worden verscheept. In de VS vereist de FCC bepaalde communicatiestaten, afhankelijk van de "klasse" van het hardwareproduct. Als schrijver moet je ervoor zorgen dat je de juiste communicatiestaat gebruikt voor het product dat je documenteert—en de verklaring op geen enkele manier bewerkt (heilige juridische woorden!).
Inhoudsopgave
De inhoudsopgave (TOC) bevat meestal ten minste een tweede niveau van detail (de kop 1's in de actuele tekst) zodat lezers precies kunnen vinden wat ze nodig hebben. Schrijvers, redacteuren en boekontwerpers discussiëren meestal over de volgorde van de TOC. Wat betreft bruikbaarheid is het veel beter om de TOC zo dicht mogelijk bij de voorkant van het boek te plaatsen, indien niet als eerste in het boek. Wat betreft wettelijke zaken maken mensen zich echter zorgen dat al die communicatiestatements, garanties, auteursrechten, handelsmerken en veiligheidswaarschuwingen eerst moeten komen. In die gevallen waarin bruikbaarheid de overhand heeft, gebruiken boeken alle tactieken die ze kunnen om dit juridische materiaal uit het voorwoord te krijgen: garanties worden op aparte kaarten geplaatst en in plastic gewikkeld met het boek of product; garanties, communicatiestatements, handelsmerken en dergelijke kunnen in bijlagen worden geplaatst.
Problemen met het maken van een mooi opgemaakte inhoudsopgave? Zie Maak een professioneel uitziende inhoudsopgave
Lijst van figuren
Technische handleidingen voor gewone gebruikers hebben meestal geen figuurlijsten. In feite hebben de figuren zelf meestal geen uitgebreide figuurtitels. Maar dit wil niet zeggen dat een figuurlijst 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 ook. Als het boek tabellen, illustraties, diagrammen, grafieken en andere zaken bevat die lezers direct willen vinden, is een figuurlijst gepast.
Voorwoord
De functie van het voorwoord is om lezers klaar te stomen om het boek te lezen. Dit doet het door:
- het karakteriseren van de inhoud en het doel van het boek
- het identificeren of zelfs kort beschrijven van het product waarvoor het boek ondersteuning biedt
- het type lezer waarvoor het boek bedoeld is uitleggen
- de hoofdzaken van de inhoud van het boek schetsen
- de speciale conventies of terminologie die in het boek worden gebruikt tonen
- ondersteuning en marketingcijfers bieden, en dergelijke
In traditionele boekuitgaven komt de inleiding vóór de inhoudsopgave; maar zoals eerder besproken in de inhoudsopgave sectie, technische uitgevers willen dat de inhoudsopgave eerder in het boek verschijnt omwille van de gebruiksvriendelijkheid.
Lichaams hoofdstukken
Oh ja, en er is echte tekst in deze boeken— het is niet allemaal voorwoord! Verder is er niet veel te zeggen, behalve dat de meeste technische boeken hoofdstukken of secties hebben, en in sommige gevallen delen. Zie het hoofdstuk over paginaontwerp voor opmaak-, stijl- en ontwerpeisen voor elementen zoals kopteksten, voetteksten, koppen, lijsten, mededelingen, tabellen, grafieken, kruisverwijzingen en markeringen.
Bijlagen
Zoals je weet, zijn bijlagen voor materiaal dat gewoon niet lijkt te passen in het hoofddeel van een boek, maar ook niet uit het boek kan worden weggelaten. Bijlagen zijn vaak de plek voor grote onhandige tabellen. Sommige technische publicaties hebben dingen zoals garanties in de bijlagen. Wat betreft de opmaak is een bijlage net als een hoofdstuk, behalve dat het "Bijlage A" of iets dergelijks wordt genoemd, en de koppen en voetteksten overeenkomen met die andere nummerings- en naamgevingsconventie (A-1, A-2, enzovoort voor pagina's in Bijlage A).
Woordenlijst
Sommige technische publicaties bevatten een sectie met gespecialiseerde termen en hun definities. Opmerkelijk is dat de meeste woordenlijsten een indeling met twee kolommen gebruiken. Typisch vormen elke term en zijn definitie een aparte alinea, met de term in kleine letters (tenzij het een eigennaam is) en vetgedrukt, gevolgd door een punt, en dan de definitie in gewone romeinse tekst. Merk ook op dat definities meestal geen volledige zinnen zijn. Goede woordenboekdefinities moeten de formele-zin definitietechniek gebruiken zoals beschreven in de definitie hoofdstuk van deze online tekst. Meerdere definities worden meestal geïdentificeerd door Arabische cijfers tussen haakjes. Glossariumparagrafen bevatten ook Zien verwijzingen naar voorkeurstermen en Zie ook verwijzingen naar gerelateerde termen.
Index
Indexen zijn ook typisch tweedelig en bevatten ook Zie verwijzingen naar voorkeurstermen en Zie ook verwijzingen naar gerelateerde termen. Zie het hoofdstuk over indexeren voor processen en richtlijnen voor het maken van goede indexen.
Lezer-reactieformulier
Vóór de opkomst van het internet en sociale media bevatten sommige technische publicaties een papieren formulier waarmee lezers opmerkingen, vragen en beoordelingen 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 wijzen slechts naar hun online locatie.
Boekontwerp en lay-out
Typisch zijn de gebruikershandleidingen en -manuals die door hardware- en softwarefabrikanten worden geproduceerd, ontworpen op een vrij sobere en spartaanse manier. Hoogtechnologische bedrijven ontwikkelen nieuwe versies en releases van hun product soms elke negen maanden. In deze context is verfijnd ontwerp gewoon niet praktisch. Hier zijn enkele typische lay-out- en ontwerpeigenschappen die je zult zien:
- Paginaformaat wordt vaak bepaald door verpakkingsoverwegingen en door de standaard paginaformaten die beschikbaar zijn bij drukkerijen. Wanneer paginaformaat geen beperking is, gebruiken sommige bedrijven het 8,5 × 11-inch paginaformaat—dit maakt de productie veel eenvoudiger voor schrijvers.
- Pagina's zijn typisch ontworpen met afwisselend rechter- en linkerpagina's. De footer voor de linker (even) pagina begint met het paginanummer en eindigt met de titel van het boek. De footer voor de rechter (oneven) pagina begint met de titel van het hoofdstuk en eindigt met het paginanummer.
- De praktijk is gemengd over de vraag of paginanummering doorlopend is in het boek of per hoofdstuk.
- Tenzij de pagina's vrij klein zijn, is het hangende kopontwerp van koppen in relatie tot pagina's vrij gebruikelijk in technische handleidingen. De hangende inspringing is meestal één tot anderhalve inch.
- Lettertypes zijn vaak 12-punts Times New Roman voor de hoofdtekst en Arial voor koppen. Standaard regelafstand en woordafstand worden gebruikt. Zie het hoofdstuk over markeren voor andere typografische problemen.
- Marges zijn vrij standaard, één tot twee inch aan alle kanten. Gewoonlijk wordt er een extra halve inch gebruikt voor de binnenmarges om te kunnen binden.
- Typisch is kleur niet gebruikt in deze handleidingen en gidsen, vaak vanwege kosten- en efficiëntieoverwegingen.
Inhoudsopgave
INHOUD
Welke inhoudsopgave (TOC) indeling je ook gebruikt, dit zijn de gemeenschappelijke normen:
- Beginpagina nummer alleen. Hoewel sommige automatische TOC-generatoren het paginabereik tonen, is de standaard alleen het paginanummer van de eerste pagina.
- Niveaus van kopjes om op te nemen. Zoals weergegeven in de inhoudsopgave hierboven, moet je de bovenste twee niveaus van koppen tonen, tenzij de gebruikershandleiding veel subkoppen heeft. De inhoudsopgave moet een overzichtelijke manier bieden om informatie snel te vinden.
- Spatiëring en hoofdletters. Let op hoe de tekstitems in de inhoudsopgave hierboven ingesprongen zijn. Eersteklas koppen gebruiken hoofdletters; tweedeklas koppen gebruiken hoofdletters bij elk belangrijk woord; derdeklas koppen gebruiken de stijl van zinnen.
- Verticale ruimte. Opmerk dat de eerste-niveau secties extra ruimte boven en onder hebben, wat de leesbaarheid verhoogt.
Afhankelijk van de vereisten van uw organisatie heeft u twee opmaakkeuzes voor inhoudsopgaven (TOC):
Deze inhoudsopgave gebruikt een decimaal nummeringssysteem voor de hoofdstuk- en sectienummers, wat gebruikelijk is in gebruikersgidsen. Andere delen in dit boek gebruiken alleen de hoofdletters romeinse cijfers voor de hoofdstukken op het hoogste niveau (zie ).
Problemen met het maken van een mooi opgemaakte inhoudsopgave? Zie Maak een professioneel uitziende inhoudsopgave
Komma's en paginanummers. Als een leider-punt formaat niet vereist is en je dit liever wilt vermijden, kun je dit algemeen aanvaarde formaat gebruiken:
Zie dit voorbeeld van een voorwoord:
Eenvoudige inhoudsopgave tekst met komma's en paginanummer.Lijst van figuren
Niet vaak opgenomen in de gebruikershandleidingen...
-->Voorwoord
Gebruiksgids Hoofdstukken
Bijlagen
Index
Andere Gebruikershandleiding Elementen
Koppen
Opsommingstekens en Genummerde Lijsten
Symbolen, Cijfers en Afkortingen
Grafieken en Figuurtitels
Kruisverwijzingen
Paginanummering
AI-aanwijzingen voor Gebruikershandleidingen
Checklist, die meestal ongelezen blijven, kunnen worden gebruikt als bron voor AI-prompts met enige aanpassing. Kopieer het volgende, plak het in een AI-systeem zoals Google's Gemini, en kijk wat je misschien bent vergeten.
Opmerking: Alle verwijzingen naar de inhoud, indeling, stijl van gebruikershandleidingen of hun componenten zijn te vinden in de online technische schrijfgids.
Wanneer je AI wilt gebruiken om een schrijfproject te evalueren, stel jezelf voor, vertel AI wie je bent en wat je wilt. Geef AI een referentiepunt voor evaluaties, zoals een online leerboek. Plaats vervolgens wat je wilt dat AI controleert in zijn evaluatie.
Pas de introductie aan om bij jouw identiteit te passen.
|
AI Prompts Gebruikershandleidingen Hallo, AI. Ik vraag je om instructies te evalueren die zijn geschreven door een tweedejaars student aan een Amerikaanse universiteit. Hieronder staat een samenvatting van de hoofdstukken van het studieboek over instructies en meldingen om als basis voor uw evaluatie te gebruiken. (Identificerende informatie gemaskeerd):
|
Gerelateerde Informatie
Hoe schrijf je gebruiksvriendelijke hulponderwerpen voor beginners. clickhelp.com
Hoe schrijf je gebruikersdocumentatie. techscribe
Gebruikershandleidingen. techscribe
Ik zou uw gedachten, reacties en kritiek over dit hoofdstuk waarderen: je antwoord—David McMurrey.
