Kracht Herziening: Structuur-Niveau Herziening

Een van de belangrijkste manieren om een ruwe versie te beoordelen, is door de inhoud te controleren—hoe voor de hand liggend is dat! Alle goede overgangen, goede organisatie en duidelijke zinsstructuur ter wereld kunnen een technische documentatie niet helpen die de juiste inhoud mist. De inhoud van een technische documentatie kan "onkruid" op verschillende manieren zijn:

• Het kan helemaal ontbreken: stel je voor dat iemand een rapport schreef over "virtuele gemeenschappen" maar nooit de moeite nam om te definiëren wat die term betekent. Het zou moeilijk zijn om vanaf het begin van dat rapport verder te komen.
• Het is er, maar niet genoeg ervan: neem hetzelfde voorbeeld—stel je voor dat de schrijver slechts een paar vage uitspraken deed over virtuele gemeenschappen. Wat nodig was, was tenminste een alinea over het onderwerp, zo niet een volledige sectie van 3 of 4 pagina's.
• Het is er, maar op het verkeerde niveau voor het publiek: Het is ook mogelijk om informatie op het verkeerde niveau te presenteren qua kennis, achtergrond of behoeften van de lezers. Stel je voor dat de schrijver wel een sectie van 3 pagina's over data caching opnam, maar geschreven voor de productontwikkelaar (een "expert" publiek), terwijl het rapport eigenlijk bedoeld was voor niet-specialisten.

Als je een gevoel kunt krijgen voor hoe de informatie in een rapportconcept ontoereikend is, ben je goed op weg om te weten wat je specifiek moet doen om te herzien. Een nuttige brainstormtool is om in termen van te denken. typen van inhoud.

Gebruik de vragen die gegeven zijn in documentinhoud om je ruwe versie te beoordelen op soorten informatie die je kunt toevoegen of wijzigen.

Controleer de structuur van je inhoud

Er zijn twee manieren om naar de organisatie van informatie in een document te kijken:

• één, behandeld in de volgende sectie, houdt in dat we kijken naar de reeks informatie stukken, om te zien of ze in de juiste volgorde staan.
• Een ander heeft te maken met niveaus van informatie. Je kunt naar de zinnen of paragrafen in een ruwe versie kijken en zien dat sommige zinnen een diepere niveau van discussie over het onderwerp aangaan dan andere. Andere zinnen fungeren als het raamwerk waarop die diepere zinnen afhankelijk zijn. Door op deze manier naar de structuur te kijken, controleer je niet alleen de organisatie, maar krijg je ook veel goede ideeën over hoe je de inhoud van de tekst kunt verbeteren.

Er is een veel gedetailleerdere uitleg beschikbaar op coördinatie en ondergeschiktheid in alinea's.

Controleer organisatie

Als je de juiste inhoud in een rapport hebt, heb je in ieder geval al het "juiste spul" beschikbaar voor lezers. Het kan echter nog steeds niet goed georganiseerd zijn—zoals wanneer je net bent verhuisd en alles een rommeltje is of nog in dozen zit. Je hebt twee essentiële vaardigheden nodig voor het beoordelen van de organisatie van een ruwe versie:

• Identificeer het onderwerp van informatiefragmenten op verschillende niveaus. Om de organisatie van een reeks alinea's te beoordelen, begin je met het denken aan een woord of een zin om het onderwerp van elke alinea te identificeren—met andere woorden, krijg een grip op elk van hen. Daarna stap je terug van die woorden of zinnen en overweeg je of ze in de juiste volgorde staan. Dat is echter slechts één niveau. Je kunt ook kijken binnen een individueel alinea voor de organisatie. In dit geval identificeer je het onderwerp van elke zin en overweeg je de volgorde van die zinnen.
• Kies de beste volgorde voor stukjes informatie. Zodra je het onderwerp van elk van de stukken informatie kent (op welk niveau je ook onderzoekt), kun je beslissen of ze in de juiste volgorde staan. Deze beslissing houdt in dat je de gebruikelijke volgordepatronen kent; hier zijn enkele voorbeelden:
  
  
  • Algemeen → specifiek: Een gangbare manier om te organiseren is om stukken inhoud van algemeen naar specifiek te rangschikken. Bijvoorbeeld, het definiëren van alle zonnecollectoren is een algemenere discussie dan het bespreken van de verschillende types zonnecollectoren. En het beschrijven van de werking van een specifiek type zonnecollector is nog minder algemeen. Dit patroon wordt hier geïllustreerd:
    
    
    Herziening met het algemene-naar-specifieke organisatorische patroon. het is een meer natuurlijke voortgang om te beginnen met het definiëren wat alle zonnecollectoren doen, en vervolgens verder te gaan naar hun verschillende types.
  • Eenvoudig, basis → complex: Een andere manier om een discussie te structureren, is te beginnen met de eenvoudige, basis- en fundamentele eenheden en vervolgens over te gaan naar de meer complexe en technische.
  • Ding-in-rust → ding-in-beweging: Een ander organisatiemodel houdt in dat eerst het ding wordt beschreven (alsof het in een foto staat), en daarna de werking of het proces wordt besproken (alsof het in een video staat). Deze aanpak kan goed werken voor een discussie over een brandstofinjectiesysteem.
  • Ruimtelijke beweging: — Als je de fysieke details van iets beschrijft, wil je misschien een patroon van fysieke beweging gebruiken, bijvoorbeeld van boven naar beneden, van links naar rechts, of van buiten naar binnen.
  • Tijdelijke beweging: — Een van de meest voorkomende patronen is gebaseerd op beweging door de tijd; organiseer de discussie over gebeurtenissen in relatie tot de temporele volgorde.
  • Concept → toepassing van het concept, voorbeeldenEen veelvoorkomend organisatiepatroon is om een concept in algemene termen te bespreken en vervolgens een toepassing ervan te bespreken. Bijvoorbeeld, een ander hoofdstuk in dit boek bespreekt voorstellen eerst conceptueel en behandelt vervolgens voorbeelden van voorstellen.
  • Data → conclusies: Een andere manier om informatie te organiseren is om gegevens (observaties, experimentele gegevens, enquête-resultaten) te presenteren en vervolgens over te gaan op de conclusies die uit die gegevens zijn te trekken. (En dit patroon is soms omgekeerd: presenteer eerst de conclusie, en dan de gegevens die deze ondersteunen.)
  • Probleem, vraag → oplossing, antwoord: Je kunt informatie ook organiseren door eerst een probleem te bespreken of een vraag te stellen en vervolgens over te gaan naar de oplossing of het antwoord.
  • Vereenvoudigde versie → gedetailleerde versie: Een nuttige manier om technische zaken aan leken uit te leggen, is te beginnen met het bespreken van een vereenvoudigde versie van de zaak, een solide begrip ervan op te bouwen, en dan terug te gaan en alles opnieuw uit te leggen, maar deze keer de technische details dik en zwaar aan te brengen!
  • Meest belangrijk → minst belangrijk: Een meer "retorisch" methode van organisatie is om te beginnen met de belangrijkste, de meest opvallende, de meest dramatische informatie eerst en vervolgens over te gaan op informatie die progressief minder is. (En dit patroon kan worden omgekeerd: je kunt opbouwen naar een climax, in plaats van er mee te beginnen.)
  • Meest overtuigende → minst overtuigende: — Evenzo kun je beginnen met het meest overtuigende argument voor je standpunt—om ieders aandacht te trekken—en dan doorgaan naar minder en minder overtuigende argumenten. (Dit patroon kan ook worden omgekeerd: je kunt naar je meest overtuigende argumenten toewerken.)

Dit zijn slechts een paar mogelijkheden. Wanneer het doel informatief is, orden je informatie zodat je ervoor zorgt dat lezers de basis begrijpen voordat ze verder gaan met de ingewikkelde, technische dingen. Wanneer het doel overtuigend is, orden je de zaken om het overtuigende effect op de lezers te maximaliseren, bijvoorbeeld door de sterkste argumenten eerst te plaatsen.

En in dat geval moet je vermijden deze benaderingen te mengenen—bijvoorbeeld, wat gegevens weggooien, dan een paar conclusies trekken, en dan dit heen en weer doen op een willekeurige manier. Houd de appels apart van de sinaasappels!

Een van de beste dingen die je kunt doen is teruggaan door een ruwe versie en controleren of je onderwerpzinnen en overzichten op sleutelpunten kunt invoegen. Wanneer we schrijven, zijn we niet normaal gesproken zeker waar een paragraaf of sectie naartoe gaat qua inhoud en logica. Zodra het daar is gekomen, is het vaak nodig om terug te gaan naar het begin en een soort overzicht toe te voegen of wat er al is te wijzigen om het overzicht duidelijker te maken. Lezers moeten weten waar ze naartoe gaan in een rapport, wat er volgende komt, en waar ze zojuist zijn geweest.

Een overzicht in een rapport is als een kaart in een nieuwe stad. Onderwerpzinnen en overzichten bieden een perspectief op wat waar is: het onderwerp, de subonderwerpen, het doel van de aankomende discussie, de relatie tot de vorige sectie en tot het document als geheel. (Een deel hiervan betreft overgangen, dat is het volgende element om te bekijken.)

Voor een gedetailleerde behandeling van dit onderwerp, zie onderwerpzinnen en overzichten.

Je kunt de juiste informatie in een rapport hebben en het goed georganiseerd hebben, maar er kan toch iets belangrijks misgaan. Lezers kunnen de "stroom" van de ideeën missen, moeite hebben om te voelen hoe de stukken informatie met elkaar verbonden zijn. Wat lezers nodig hebben, is continue begeleiding—dit is wat jij, de schrijver, biedt. En wat je gebruikt om die begeleiding te bieden, wordt overgangen—genoemd, verschillende middelen die lezers helpen door een document. Er is (of zou zeker moeten zijn) een logica die elke zin in een document met elkaar verbindt en die een bepaalde volgorde aan die zinnen dicteert.

Zie het hoofdstuk over coherentie en overgangen voor een gedetailleerde discussie en voorbeelden.

Een laatste manier om je ruwe concept op structureel niveau te beoordelen, is door te controleren hoe je de alinea-afbrekingen hebt gedefinieerd. Alinea's zijn vreemde wezens—sommige schrijvers geloven dat ze niet bestaan en gewoon arbitraire onderbrekingspunten zijn die schrijvers overal en wanneer ze maar willen inbrengen. Sorry—in technisch schrijven is de alinea een belangrijke speler in de strijd om helderheid en begrip. Hoewel het niet altijd mogelijk is, zouden alinea's moeten plaatsvinden waar er een verschuiving is in onderwerp of subonderwerp of een verschuiving in de manier waarop een onderwerp wordt besproken.

Op een enkelregelige volle pagina met tekst, kijk voor ten minste één tot vier alinea-afbrekingen—er is niets magisch aan dat gemiddelde, dus behandel het niet alsof het wet is. Kijk nog een keer naar die lange alinea's en controleer op de mogelijkheid van alinea-afbrekingen.

Ik zou uw gedachten, reacties en kritiek over dit hoofdstuk op prijs stellen: jouw reactie—David McMurrey.