Strukturerad dokumentation och XML

En presentation över ämnet: "Strukturerad dokumentation och XML"— Presentationens avskrift:

1

2 Strukturerad dokumentation och XML

3 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

4 XML = eXtensible Markup Language

5 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

6 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.

7 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>

8 Mer information XML Sweden:

9 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

10 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

11 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

12 ”Single-sourcing” och återanvändning

13 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

14 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

15 Enhetlig dokumentation
Moduluppbyggd, strukturerad dokumentation kan även implementeras globalt Med ett globalt CMS ges begreppet återanvändning av information en helt ny innebörd

16 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

17 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.

18 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

19 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.

20 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

21 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.

22 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.