Kapittel 2. Dokumentstruktur

DocBook er utformet for å lage dokumenter der klar struktur er viktig. Oppmerking i DocBoook er innholds- og funksjonsorientert. Presentasjon er i utgangspunktet skilt fra skrivingen.

Hovedstruktur i en typisk håndbok

  1. Innledning. En innledning skal gi leseren nok informasjon til å finne ut om dette dokumentet er det riktige for det aktuelle formålet.

    Derfor bør innledningen være et kort kapittel som starter med en beskrivelse av hva dokumentet handler om, og hvem man antar leseren er, med antydning om leserens bakgrunn. Deretter følger en kort oversikt over eventuelle konvensjoner, der slike ting som hvilke skrifter som betyr hva osv er angitt. I dokumenter på mer enn noen ganske få sider kan det også være på sin plass å ha en korte oppsummeringer av enkeltkapitlene, helst med kryssreferanser (klikkbare i elektronisk utgave) til hvert kapittel.

  2. Dokumentets hoveddel. Her beskriver du det dokumentet handler om, inndelt i de kapitlene og underdelene som følger av logisk gjennomarbeiding av emnet.

  3. Bakgrunnsmateriale og referanser. Dette dreier seg typisk om materiale som mange av leserne ikke er helt avhengige av for å forstå hovedteksten, men som kan gi nyttig bakgrunnsinformasjon for spesielle situasjoner eller dypere studier. Typisk er dette materiale som det er naturlig å legge til tillegg (appendix).

    I noen dokumenter vil det også være naturlig å ha et tillegg med angivelse av planlagt eller antatt videre utvikling av dokumentet.

I tillegg vil det i de fleste tilfeller bli generert innholdsfortegnelse og fortegnelser over figurer og tabeller automatisk. Endelig vil det for dokumenter over en viss størrelse (IEEE opererer med en grense på 40 sider) være naturlig med indeks (emneregister), som blir generert på grunnlag av indekseringskommandoer i dokumentet.