Transcript Ette_Strukturerad_dokumentation

Strukturerad dokumentation
och XML
Introduktion till strukturerad dokumentation
 Strukturerad dokumentation innebär att
informationen ”taggas” dvs märks upp
 Taggarna/elementen kommer till exempel från den
öppna standarden DITA
 Elementen beskriver innehållet
 Innehåll och layout är helt separerade
 XML är ett standardformat för att skapa strukturerad
dokumentation
XML
XML = eXtensible Markup Language
Vad är XML?




XML är ett märkspråk
Standard sedan 1998
Ren text
Syftet är att kunna utväxla data mellan
olika informationssystem
 XML-koden definierar INTE vilka
element eller attribut som kan
användas
DTD
 DTD = Document Type Definition
 Ett sätt att beskriva strukturen på ett
XML-dokument, dvs vilka element,
attribut och entiteter som är tillåtna
eller obligatoriska, samt i vilken
ordning dessa får förekomma
 Standardiserade DTDer: DITA,
S1000D, docbook, m.fl.
Exempel
<?xml version="1.0" encoding="iso-8859-1"?>
<books>
<book language="english">
<title>Macbeth</title>
<author>Shakespeare</author>
</book>
<book language=”swedish">
<title>Röda rummet</title>
<author>August Strindberg</author>
</book>
</books>
Mer information
 XML Sweden: http://www.xml.se/
När ska man använda
strukturerad dokumentation?
 Många uppdateringar
 Liknande innehåll i många olika dokument
 Samma information publiceras i flera olika media
 När man vill ha ett enhetligt utseende och innehåll
i sin dokumentation
 När dokumentationen översätts frekvent
Fördelar med strukturerad
dokumentation

Bättre kvalitet på innehållet

Effektivare produktion av dokumentation

Enklare hantering av uppdateringar och
konstruktionsändringar

Förenklar samtidig publicering i flera media

Återanvändning av innehåll

Plattformsoberoende

Kostnadsbesparande
Modularitet och återanvändning





Strukturerad information består av små bitar information,
dessa kallas moduler
Modulerna kan vara olika stora beroende på hur de skall
användas
Modularisering är ett sätt att göra information mer
återanvändbar
Storleken på modulerna ger nivån på återanvändningen
Återanvändning innebär att man inte skriver sådant som redan
finns skrivet
 Liknande produkter delar ofta på mycket information
 Utan tekniska hjälpmedel sker återanvändningen genom att
kopiera och klistra in, i värsta fall skrivs information om från
början
”Single-sourcing” och
återanvändning
Publicera till flera format

XML möjliggör publicering i flera olika format från samma
källmaterial. Detta på grund av att innehåll och layout är helt
separerade.
Informationsprodukt
PAPPER
STILMALL
Publiceringsverktyg
CMS
STRUKTURERAD
INFORMATION
Informationsprodukt
WWW
Informationsprodukt
CD
CMS (Content Management System)
 Administration av strukturerad information
 Versions- och ändringshistorik
 Möjliggör återanvändning av information
 Hantering av användarkonton/behörigheter
 Arbetsflöden
 Hantering av språkversioner
 Många olika CMS på marknaden
Enhetlig dokumentation
Moduluppbyggd,
strukturerad
dokumentation
kan även
implementeras
globalt
Med ett globalt
CMS ges
begreppet
återanvändning
av information en
helt ny innebörd
Viktigt vid implementering
 Använd en färdig produkt, inte en produkt i
utvecklingsfas
 Planera väl
 Analysera innehållet
 Bestäm slutprodukten så snabbt som möjligt
 Fokusera på en sak i taget (innehåll, utseende,
struktur)
 Tydlig dokumentationsstrategi
 Ge alla inblandade tillräckligt med tid
 Använd expertis
Kunden äger informationen

De flesta system exporterar data i öppna, internationella
standarder (XML, DITA, RDF)

Informationen är plattformsoberoende:
 Information i XML-format kan enkelt flyttas mellan system.
XML-filerna inklusive metadata kan exporteras från CMS.
Lätt att modifiera stora datamängder
 XML är ett textformat, möjliggör
behandling av många filer samtidigt
med hjälp av script
 Rapporter
 Ändringar
Lagar, standarder
 Beroende på produkt och land så måste man följa
olika standarder och lagar när man jobbar med
teknisk dokumentation.




Företags interna standarder och riktlinjer.
Branschspecifika standarder och riktlinjer.
Nationella regler och lagar.
Den vanligaste standarden inom industrin är maskindirektivet
(CE-märkning). Direktivet omfattar bland annat fastläggande
av krav för att undvika olyckor i industriella maskinparker vid
konstruktion, tillverkning, drift och underhåll av maskiner.
Gäller från 29 december 2009 i EU.
Kontrollerat språk
 Fördelar:





Risken för missförstånd minskar
Dokument är lättare att läsa och förstå
Enhetlig terminologi
Större återanvändbarhet
Lättare att översätta
Kontrollerat språk forts.
 Typiska skrivregler:






Varje ord har bara en enda betydelse.
Stava alltid likadant.
Förkortningar ska förklaras.
Använd inga synonymer.
Skriv i presensform.
Använd kulturneutrala illustrationer.
Kontrollerat språk forts.
 ASD Simplified Technical English (STE)
 Började utvecklas 1979 för den kommersiella
flygindustrin, sedan även försvarsindustrin
 Begränsad och standardiserad del av engelskan
 Skrivregler och ordlista
 Reglerar bl.a. längden på meningar och
paragrafer, hur många substantiv som får
användas i rad, hur varningar ska skrivas och vilket
tempus man ska använda.