Skriftlig Info ➜ DITA-publisering ➜ DITA topics ➜ DITA Task topic

DITA Task topic

Her er en den "offisielle" beskrivelsen fra Oasis (oversatt av meg):

Jeg velger å definere en task topic slik:

Task topics er de viktigste emnene i en publikasjon. De forklarer hvordan leseres skal gjøre noe. Viktigheten av task topics i DITA er basert på prinsippet om oppgaveorientert skriving. Det prinsippet er basert på følgende påstander:

• Det er ingen som bryr seg om hvordan noe virker.
• Det eneste brukeren er interessert i er å få produktet til å gjøre den jobben det er kjøpt inn for å gjøre.
• Når leseren har spørsmål, eller noe stopper opp, er det ingen som vil lese en svær bruksanvisning.

Innholdet i task topic skal forfattes etter følgende prinsipper:

• Teksten skal presentere det leseren trenger for å utføre oppgavene, og intet annet.
• Hver handling skal forklares i imperativ med nummererte trinn.
• Hvert trinn i prosedyren skal bare inneholde en handling.
• Hver handling skal vises i den rekkefølge de skal utføres.
• Hver handling som skal utføres må klart skilles fra eventuelle konseptuelle beskrivelser og resultater.

Normal praksis er at en prosedyre ikke skal inneholde flere enn maksimalt ni trinn. Hvis du får flere trinn enn dette bør du vurdere å slå sammen trinn, etablere underliggende trinn (<substeps>) eller dele prosedyren i to eller flere separate task topics.

For ordens skyld vil jeg nevne at DITA-standarden beskriver to forskjellige task topics; "General" og "Strict". Som det fremgår av navnene er den ene litt "strengere" enn den andre. Den største forskjellen er at "General" task topic tillater deg å sette inn ekstra <section>-elementer.

En DITA task topic er strukturert som følger.

<title>

Alle task topics skal ha en tittel.

<shortdesc>

Alle task topics må ha en "short description" som definerer kontekst.

<prolog>

Dette elementet kan brukes for å legge inn indeks-informasjon. Indeks-informasjon kan forøvrig også legges inn andre steder i topic'en.

<taskbody>

Dette elementet brukes for å samle all informasjonen i topic'en. Se <taskbody>.

Av disse elementene er det bare <title> og <taskbody> som er obligatoriske.

<prereq>

Dette er et valgfritt <section>-element som brukes for å beskrive hva brukeren trenger å vite, eller trenger å ha, før oppgaven kan starte. På engelsk kalles dette prerequisites.

Dette elementet skal ikke inneholde noe leseren skal gjøre!

<context>

Dette er et valgfritt <section>-element som brukes til å formidle bakgrunnsinformasjon. Denne informasjonen skal hjelpe leseren til å forstå formålet med oppgaven og hva som oppnås når den utføres riktig. Informasjonen i <context>-elementet skal ikke erstatte konseptuell informasjon. Hvis du har informasjon som du mener leseren kan ha nytte av kan du ta med kortfattet informasjon om dette. Hvis oppgaveforståelsen krever omfattende konseptuell informasjon skal det henvises til en concept topic.

<steps>

Dette elementet gir en numerisk liste over de oppgavene som skal gjøres. Se <steps>.

<result>

Dette valgfrie <section>-elementet brukes for å beskrive eventuelle resultater etter at oppgaven er utført.

<example>

Dette valgfrie <section>-elementet brukes for å beskrive et eventuelt eksempel.

<postreq>

Dette valgfrie <section>-elementet brukes for å beskrive hva leseren eventuelt må gjøre etter at oppgaven er utført.

Av disse elementene er det bare <steps> som er obligatorisk.

De elementene som er bygget opp av <section>-elementer kan inneholde vanlig multimodal tekst, og de aller fleste standard DITA-taggene kan brukes.

<steps>-elementet har en helt spesiell oppbygning. Det kan inneholde ett eller flere <step>-elementer. Hvert av disse inneholdet ett <cmd>-element. Etter <cmd> kan du bruke flere elementer for å utdype den handlingen som skal utføres, presentere konseptuell informasjon, eller forklare eventuelle resultater av handlingen.

<step>

Dette obligatoriske elementet skal inneholde en handling. Se <step>.

<steps>-elementet kan inneholde mange <step>-elementer. Hvert <step>-element kan bruke de elementene som listes opp her.

<cmd>

Dette obligatoriske elementet skal inneholde den handlingen som leseren skal utføre. Setningen i <cmd>-elementet skal skrives i imperativ (bydende) form med verbet først.

<info>

Dette valgfrie elementet kan brukes for å legge inn multimodal informasjon. Elementet skal ikke inneholde noe leseren skal gjøre.

<stepresult>

Dette valgfrie elementet kan brukes for å legge inn multimodal informasjon. Elementet skal inneholde tekst som beskriver resultatet av det som ble utført i <cmd>-elementet. Elementet skal ikke inneholde noe leseren skal gjøre.

<substeps>

Dette valgfrie elementet kan brukes for å legge inn underordnede step. <substeps> kan inneholde et gitt antall <substep>-elementer. Hvert av disse inneholder ett obligatorisk <cmd>-elementet samt eventuelle <info> og <stepresult> elementer. <substep>-elementet kan ikke inneholde underliggende <substeps>.

<step>-elementet kan også inneholde andre underliggende elementer, men de er ikke så mye brukt.