Skriftlig InfoDITA-publiseringDITA-elementerDITA <title>

DITA <title>

I DITA er <title> det første elementet alle slags emner (topics), og det er obligatorisk. Når du skal lage en tittel er det viktig at den så godt som mulig beskriver hva emnet handler om.

Den offisielle beskrivelsen av <title>-elementet ser slik ut:

The <title> element contains a heading or label for the main parts of a topic: the topic as a whole, sections, examples, and labelled content such as figures and tables. The element also can be used to provide a title for a map or a relationship table; when used in a relationship table, the title typically is used as a authoring convenience and is not rendered for display to an end user.

Oasis: <title>, hentet fra https://docs.oasis-open.org [1]

Som det fremgår av definisjonen kan <title>-elementet brukes flere steder. I denne sammenhengen er de viktigste stedene disse:

  1. <title> i DITA Task topics
  2. <title> i DITA Concept og Reference topics
  3. <title> definerer kontekst og muliggjør omfattende gjenbruk
  4. <title> i <section>
  5. <title> i <figure> og <table>

Tips

Under temaet "Skriving" finner du generell informasjon om hvordan du kan forfatte en fornuftig tittel til en prosedyre.

<title> i DITA Task topics

<title> er det første elementet i DITA task topics, og det er obligatorisk. De samme generelle reglene for gode overskrifter gjelder også her.

Det er alltid viktig å unngå titler som ikke helt klart forteller leseren hva prosedyren beskriver. Forvirrende overskrifter utløser bare irritasjon når man søker i databaser eller websider for å finne informasjon, og deretter ender opp med et avsnitt som forklarer prinsipper, teorier eller annen konseptuell informasjon. For å klart skille prosedyrer fra konseptuelle forklaringer, og for sikre seg mot unødvendig irritasjon hos leseren, er det lurt å bruke en av de følgende skrivemåtene:

Eksempel 1

Testing av strømforsyning AX215-24V

Test strømforsyning AX215-24V

Hvordan teste strømforsyning AX215-24V

Diskuter dette i dokumentasjonsgruppen din, og bli enige om en standard!

<title> i DITA Concept og Reference topics

I Concept og Reference topics gjelder det samme. Her er det viktig at tittelen du velger ikke kan misforstås med en prosedyre. Den enkleste måten å gjøre dette på er å unngå verb i tittelen, og heller identifisere funksjon, objekt eller enhet. Det er svært mange måter å gjøre dette på, så igjen er det viktig at dere diskuterer det i dokumentasjonsgruppen for å bli enige om en standard.

Eksempel 2

Utskrifts-funksjonen

Beskrivelse av Utskrifts-funksjonen

Slik virker Utskrifts-funksjonen

Dere kan gjerne også lage forskjellige standarder for objekter i brukergrensesnittet og fysiske enheter. Det gjør det enklere for leseren å identifisere de ulike beskrivelsene.

Eksempel 3

Utskrifts-funksjonen

Beskrivelse av strømforsyning AX215-24V

<title> definerer kontekst og muliggjør omfattende gjenbruk

I DITA brukes <title> og <shortdesc>-elementene til å definere kontekst. Hva er det egentlig dette emnet handler om? Hvilken funksjon er det som brukes, hvilken fysiske enhet skal det jobbes med, hvilken dialogboks eller meny beskrives?

Denne definisjonen av kontekst er spesielt viktig hvis du er flink til å gjenbruke tekstelementer. Når <title> og <shortdesc>-elementene forteller leseren navnet på det objektet emnet handler om er det ikke nødvendig å gjenta dette navnet lengre ned i teksten. Når navnet kan utelates gir det deg mulighet til å bruke generiske substantiver i stedet. Det betyr at du forhåpentligvis kan hente ferdiglagde og ferdig oversatte setninger fra et rikholdig arkiv.

Dette lar seg enklest beskrives med en eksempel.

Eksempel 4

I min installasjonsmanual har jeg en prosedyre som beskriver hvordan strømforsyningen skal monteres. Tittelen på prosedyren er:

Installing the Power Supply Unit

Her har jeg i <title>-elementet definert hvilken enhet det er som skal installleres; Power Supply Unit. Det samme navnet gjentas i <shortdesc>-elementet rett under tittelen. Dette betyr at jeg i hele resten av prosedyren ikke trenger å gjenta navnet "Power Supply Unit". I alle etterfølgende setninger kan jeg bruke det generiske substantivet "unit". Et eksempel er:

Mount the unit to the bulkhead using the bolts provided.

Siden navnet "Power Supply Unit" er definert i starten av prosedyren forstår leseren intutivt at det er strømforsyningen det er snakk om. Den samme generiske setningen kan jeg deretter gjenbruke for alle fysiske enheter som heter et eller annet med "Unit". På den måten kan jeg bygge opp et stort antall installasjonsprosedyrer som alle bruker de samme tekstelementene. Kun tekstene i <title> og <shortdesc>-elementene er forskjellig fra en prosedyre til den neste.

Tips

Et av de viktigste formålene med modulær og emnebasert skriving er gjenbruk av informasjonselementer. Gjenbruk betyr å bruke disse elementene om igjen. Gjenbruk av tekst er ikke det samme som å kopiere den og lime den inn et annet sted. Det den samme teksten som brukes om igjen. Hvis kildeteksten endres blir teksten endret alle stedene den er brukt. Hvilke kildeteksten oversatt blir den også oversatt alle de stedene den er brukt.

<title> i <section>

For å dele opp teksten og gjøre den enklere å lese kan du i Concept og Reference topics bruke <section>-elementet. I dette elementet er detmulig å sette inn en <title>. DITA-koden ser slik ut:

<section>
   <title>Tittel-tekst</title>
   ...
</section>

Hvis du velger å fragmentere teksten på denne måten brukes tittelen for å identifisere innholdet i <section>-elementet.

Hvis du bruker flere <section>-elementer etter hverandre, og velger å bruke <tittel> på et av de første må alle etterfølgende <section>-elementer også ha. Hvis ikke vil ikke leseren se hvor den en <section> slutter og den neste begynner.

I Task topics er <prereq>, <context>, <result>, <example> og <postreq> elementer som tilsvarer <section>-elementet i Concept og Reference topics. Normalt vil disse elementene få automatiske titler som er definert i stilarket.

Merk at tittelen i en <section> ikke vil vises i dokumentets innholdsfortegnelse.

<title> i <figure> og <table>

Både <figure> og <table>-elementene kan bruke en <title>, og tittelen blir brukt for å identifisere henholdsvis figur og tabell. Disse titlene vises ikke i innholdsfortegnelsen. Hvis stilarket ditt støtter det kan disse titlene brukes til å gi en automatisk liste over figurer og tabeller.

Relaterte tekster

Skriving: Bruk en tittel som beskriver oppgaven prosedyren skal forklare

Metodikk: Spar tid og penger med gjenbruk


Referanser

  1. Oasis: <title>, docs.oasis-open.org, (Link)

Alle eksterne linker åpner i et nytt vindu. Jeg tar ikke ansvar for informasjon på eksterne nettsteder, selv om jeg har linket til dem. Vennligst rapporter linker som ikke virker.

Informasjonen på denne siden representerer mine personlige meninger, og min egen forståelse av temaet som beskrives. Du kan gjerne linke til siden, men ikke kopiere større deler av innholdet uten tillatelse. Jeg tar ingen ansvar for eventuelle feil, misforståelser eller manglende informasjon om omfattende temaer. Jeg tar heller intet ansvar for feil du måtte gjøre eller forårsake som et resultat av feilaktig eller manglende informasjon. Du kan gjerne bidra med kommentarer, egner erfaringer eller utfyllende informasjon. Se Kontaktinformasjonen.