XML-basert dokumentasjon Erfaringer med innføring av xmlbasert dokumentasjonsverktøy hos Kongsberg Seatex Sissel Kolvik Tidligere IBRUK as nå SK Teknisk Dokumentasjon sissel@kolvik.priv.no 1 Hvorfor ikke bruke Word? Mengden dokumentasjon 12 ulike produktfamilier 60 ulike manualer 6000 9000 sider dokumentasjon Mye er ganske likt eller helt likt i flere manualer Vanskelig å oppdatere på en kostnadseffektiv måte og samtidig vedlikeholde god kvalitet på dokumentasjonen. 2 1
Hvorfor xml? Single source publishing Sparer tid og øker effektiviteten Gjenbruk av informasjon (tekst, bilder og illustrasjoner) Enkelt å publisere til PDF, HTML, RTF Enhetlig layout som kommer av seg selv ferdig definerte stylesheets. 3 XML gjør at du kan Skrive alt i ASCII Skille mellom dokumentenes innhold og hvordan de ser ut Beholde all grafikk som separate filer unngår insert picture from file Gjenbruke informasjon Publisere til ulike formater Automatisk få et konsistent utseende Forbedre informasjonsstrukturen. 4 2
Hvordan lage mange bøker ved hjelp av kildefiler? 5 Seatex og IBRUK November 2008 mars 2009: IBRUK kom med i et forprosjekt som skulle evaluere mulige alternativer til Word Mulige løsninger som ble vurdert: Word-baserte verktøy Arbortext Konklusjon Arbortext anbefalt fordi dette allerede var i bruk i Kongsberg Maritime De andre alternativene Word Analyzer fra IBRUK Vente og se hva Microsoft gjorde med xml-funksjoner i Word. 6 3
Videre arbeid med Word hos Seatex Mars 2009 november 2010: Laget ny struktur på Word-dokumenter basert på innhold som kunne gjenbrukes Bygget manualer basert på filer + spesifik tekst for hvert enkelt dokument Insert -Object text from file - velg fil insert as link Mye dobbeltskriving likevel ikke mulig å profilere eller legge inn variabler. 7 Hvorfor slet Seatex med Word? Stor sannsynlighet for kræsj når filene blir store ganske irriterende i lengden og endringer kan gå tapt Kræsj tar tid å fikse, særlig hvis endringer er blitt borte må skrive på nytt Tidkrevende å oppdatere 10 ulike dokumenter når man kan ha bare to (DPS 122/132/200/232/4D Inst + User): Nesten umulig å få med seg endring alle steder, særlig hvis dokumentene ikke releases til samme tid Bruker mye tid på formattering av stiler og layout i etterkant Bra med Word ser hvordan det blir med en gang. 8 4
Hvorfor ikke Word som editor? Word er en tekstbehandler og ingen editor Utdrag fra en artikkel av Scott Abel i ISTC magazine "Communicator", 2008. Fact: Microsoft Word is a word processor. Two more facts: Microsoft has not marketed Word as an XML editor and doesn't plan to. Why? Because Word is not an XML authoring tool, no matter how often we hear the words Word and XML used together. While Word may indeed understand and use some XML, it doesn't use XML in the same way that technical communicators need it to. Instead, it uses XML to transfer information back and forth between Microsoft Office products. Useful? Yes. XML authoring? Not even close. 9 Utfordringene ved bruk av baserte xml-verktøy Krever gjennomtenkt struktur på dokumentasjonen Alle «kan» Word Krever en del arbeid før det kan tas i bruk Evt tilpassing/endring av struktur Etablere dtd (document type definition DocBook, DITA) Etablere / tilpasse style-sheet Lære å bruke editor mm. Kontrollert bruk av filnavn og hvor filer lagres Koster mer enn Word Mindre mulighet for finjustering av layout stylesheet bestemmer. 10 5
Seatex i dag Har begynt å bruke Arbortext Har konvertert 24 manualer - To produktgrupper Hvorfor ble Arbortext valgt Brukes allerede i Kongsberg Maritime - de får en del gratis dtd, style sheets, publisher Editor er veldig god Styler-funksjon er veldig effektiv for å utvikle og vedlikeholde stylesheets God publisering Enkel tilpasning av DocBook dtd Editor kan brukes av utviklingsressurser alle kan lære å skrive Gode erfaringer fra andre over flere år Input kan også komme fra andre editorer. Validering mot dtd. 11 Priser Arbortext Editor Fast lisens 6590 SEK Flytende listens en om gangen 25650 SEK Arbortext Styler: 35000 SEK i 2005 for å lage og vedlikeholde stylesheets Arbortext Import: ca 20000 SEK automatisk import fra andre format som for eksempel MSWord Arbortext Print Composer: 11000 SEK i 2005-2007 (installert på en PC) Arbortext Publishing Engine: ca 300000 SEK i 2008 (installer på server for slik at alle i nettverket kan publisere) Alle lisenser har 20% årlig vedlikehold (teknisk support + SW oppgradering). 12 6