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 = 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> </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 CMS Publicerings- verktyg Informationsprodukt WWW STRUKTURERAD INFORMATION 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. http://www.asd-ste100.org/