Principer för dokumentation från Sambruksprojekt

Transkript

1 Utfärdad Sven-Håkan Olsson Godkänd av Dokumenttyp Memo Status Under arbete Identitet (se filnamn) Version (se filnamn) Sid 1 (9) Versionsdatum Principer för dokumentation från Sambruksprojekt Principer_dok_Sambruk_v1_ doc Projektsamordnare Lotta Ruderfors lotta.ruderfors@sambruk.se

2 2(9) Historik och beslutade ändringar: Datum Ändring Ändrad av Första förslag Sven-Håkan Olsson Bilagor: Nr Beteckning Version Identitet - Innehåll: 1. Inledning och behovsbild Några generella principer Dispens Detaljerade generella principer Principer för dokument Principer för programkällkod Principer för tekniska specifikationer Principer för Huvudsaklig sajtstruktur Begränsad access... 8

3 3(9) 1. INLEDNING OCH BEHOVSBILD Det som skapas och levereras från alla Sambruksprojekt (kallas ofta i projekten för utgåvor, artefakter eller leverabler) bör hanteras på ett strukturerat sätt för att inte gå förlorat för framtiden. Mycket pengar och energi riskerar annars läggas ner helt i onödan. Idag sparas endast viss info på Sambrukssajten annat blir liggande på projektdeltagarnas C-/H-diskar eller i någon projektmapp i hemmakommunen. Andra gånger används kanske Projektplatsen, något ftp-arkiv eller GoogleDocs och sedan blir det bortglömt där eller lösenorden kommer bort ett år efter projektavslut. Flera gånger har det varit svårt att återanvända t.ex. tidigare upphandlingsunderlag eller andra dokument eftersom de inte kunnat återfinnas, eller också har det kostat värdefull tid att få fram dem. I andra fall har man kanske hittat en pdf-fil på Sambrukssajten men att återskapa ett vettigt redigerbart Word/Writer-dokument från en pdf tar massor av improduktiv tid. Ännu mer uttalat är problemet ifall programkällkod har levererats från ett Sambruksprojekt. Det kanske t.o.m. totalt är nedlagt miljoner kr i utveckling och ändå hanteras utgåvorna sedan skakigt. Ytterligare ett behov är att långsiktigt kunna återfinna Begreppsmodeller, Nyttomeddelanden och s.k. xml-definitioner. När man ger ut sådana måste man räkna med att ta ansvar för deras tillgänglighet i minst år. Här behövs även en teknisk nerladdbarhet på en länkadress (URL) som är stabil över hela denna tid (s.k. permalänk) eftersom det finns risk att vissa program ger exekveringsfel annars. En annan aspekt är versionshantering. Många dokument och tekniska specifikationer måste vara tillgängliga i olika versioner parallellt, och för programkällkod är kravet på versionering oeftergivligt. Behovsbilden är alltså ganska omfattande. Å andra sidan tenderar dokumentarkivsprojekt liksom införande av versionshanteringssystem för källkod att bli komplexa, dyra och tidskrävande. Nedanstående principer är därför ett försök att finna en enkel, mycket pragmatisk ambitionsnivå och med konkreta formuleringar. Grundidén är att använda så mycket som det är möjligt för att slippa fragmentering. Periodiskt bör man sedan utvärdera hur det har fungerat och kanske överväga ändringar i principerna. Dessa ska alltså i sig versioneras!

4 4(9) 2. NÅGRA GENERELLA PRINCIPER 2.1. Dispens En grundtanke är att principerna i detta dokument ska vara tydliga och lätta att följa. Därför ska det inte av slentrian bli så att man avviker från principerna av bara farten. Not-inventedhere-fenomenet är inte produktivt och det är inte speciellt svårt att följa dokumentets principer. Å andra sidan kanske man ibland mottar en hel dokumentomgång från ett värdefullt projekt utfört internt i en Sambrukskommun eller köper ett projektutförande från någon konsult som redan har ett dokumentmallpaket som man vill återanvända. I dessa fall ska man förstås se möjligheter med dispens från reglerna. Huvudsaken är att någon vettig form av dokument- och versionsmärkning finns och att utgåvor läggs upp på Sambrukssajten, må det så vara som ett dokumentpaket i en zip-fil med ett beskrivande namn ifall delfilerna skulle krocka med principerna Detaljerade generella principer Nedan följer några detaljer som här specificeras inledningsvis för att slippa upprepas i nedanstående kapitel. Versionsnummer och utgåvedatum har format enligt v9_8_ Orsaken till att datum inkluderas är att filsystemens datummärkning vanligen går förlorad i samband med samverkan över e-post eller olika arkiveringar. På liknande sätt är det mycket olämpligt att man inne i dokument använder automatiska datumfält som baseras på sparandedatum eller dagens datum. Versionsnumrereringen internationell konvention - att stega upp första versionssiffan anger en större omgörning ("major release") medan andra siffran stegas upp vid alla mindre omgörningar ("minor release"). För enklare dokument kan det räcka med en versionssiffra, såsom v12_ Dokument som i sig utgör utgåvor av en version av ett ramverk, en policyskrift etc ska på ovanstående sätt ha specifika versionssiffror som uttrycker detta. Dock kan man behöva arbetsdokumentversioner under samarbete som exempelvis inbegriper e-postande mellan olika personer. Ett sådant exempel är Öppen Teknisk Plattform, ÖTP, som successivt utkommer i utgåvor, och varje sådan utgåva behöver ha dokumentversionering inom sig. Då används under arbetets gång en omgång till av versionssiffror enligt följande mönster: Sambruk_OTP_v2_0_dokv_12_ doc.

5 5(9) Fastställd utgåva däremot ska bara heta t.ex. Sambruk_OTP_v2_0_ doc. Filnamn ska inte innehålla specialtecken, svenska bokstäver eller blanktecken. Detta av två anledningar, dels blir inte filnamnen då helt kompatibla mellan plattformar som Windows, Mac och Linux, dels förstörs vanligen filnamnen vid nerladdning från webbar eftersom url-konventionen ser ut som den gör (procenttecken, parenteser och andra skräptecken uppenbarar sig efter nerladdning). Huvudprincipen är att naturliga blanktecken ersätts med _ medan naturliga bindestreck får stå kvar, liksom att Å/Ä/Ö ersätts med A/A/O. Var konsekvent vid användningen av små/stora bokstäver eftersom t.ex Linux skiljer på filen ABC.doc och Abc.doc. Skulle det vara mycket opraktiskt i ett projekt att följa principerna ovan så ska en färdig utgåva av filerna paketeras ihop i zip-format, men zip-filens namn ska däremot följa principerna, samt vara tydligt beskrivande. 3. PRINCIPER FÖR DOKUMENT Om inte synnerliga skäl talar emot det ska filnamn på dokument i slutet av själva filnamnet ha versions- och utgåvedatum enligt avsnittet Detaljerade generella principer ovan. Exempel: Principer_dok_Sambruk_v1_ doc Dokumentmärkning, versionshantering etc sköts i vissa fall inom något avancerat dokumenthanteringssystem. Då är ibland tanken att dokumentmetadata helt ligger i dokumenthanteringssystemet och att dokumentfilen i sig inte innehåller något av den arten, liksom att filnamnet är helt icke-beskrivande. Detta må vara önskvärt inom en viss, sammanhållen organisation, men är vanligen inte dugligt för Sambruksprojekt eftersom deltagarna finns spridda inom helt olika kommuner, organisationer, konsultföretag och forskarsamarbeten. I de fall som man ändå kan använda ett avancerat dokumenthanteringssystem i ett Sambruksprojekt så är grundprincipen att delversioner, arbetsmaterial och utgåvor gärna hanteras inom dokumenthanteringssystemet men att färdiga utgåvor ska kopieras in på för att finnas arkiverade samlat. På samma sätt gör man då dokument hanteras inom lösningar som Projektplatsen eller GoogleDocs - färdiga utgåvor ska kopieras in på Vissa sorters utgåvor har ett speciellt värde som fastställts enligt principerna Sambruksgemensamt Material, SGM. Ifall access till dessa filer bör begränsas, se avsnittet Begränsad access nedan. Det har funnits en olycklig tendens att endast resultat i form av pdf-filer har lagts upp på Sambrukssajten vilket gjort det mycket arbetssamt att redigera vidare för en kommande utgåva. Därför ska grunddokumentfiler också kopieras in på (t.ex.

6 6(9) Word/Writer-filer). Ifall access till dessa filer bör begränsas, se även avsnittet Begränsad access nedan. 4. PRINCIPER FÖR PROGRAMKÄLLKOD Källkod till program hanteras vanligen inom något slags sammanhållet utvecklingsverktyg, såsom Eclipse eller Visual Studio. Sajtutveckling kan tänkas ske i ett publiceringsverktyg, s.k. Content Management System (CMS). Versionshantering och s.k. Configuration Management (CM) sker ibland i ett annat verktyg eller i ett som är integrerat med utvecklingsverktyget, såsom Team Foundation eller Subversion. Strukturen inom valda verktyg dikterar vanligen vissa saker vad gäller katalogstruktur, filnamn etc. Det finns ingen praktiskt möjlighet att skulle kunna förstå alla dessa varianter. Arbetsversioner, testversioner, rättningar, fastställda utgåvor med mera hanteras därför på vanligt sätt inom de här verktygen på det sätt som respektive projekt etablerat men färdiga utgåvor ska kopieras in på för att finnas arkiverade samlat. För att göra detta praktiskt ska en utgåva av källkodspaket läggas ihop i en zip-fil med ett tydligt namn enligt principerna ovan och placeras på Sambrukssajten. 5. PRINCIPER FÖR TEKNISKA SPECIFIKATIONER Vissa tekniska specifikationer, främst s.k. xml-scheman och wsdl-specifikationer behöver finnas maskinellt åtkomliga på en öppen och permanent länkadress (URL). Principen ska vara att utgåvor av de tekniska specifikationsfilerna dels ska arkiveras inom sitt respektive Sambruksprojekts yta på Sambukssajten för att vara återfinnbara i sitt sammanhang dels kopieras in på adressen för att vara maskinellt åtkomliga på ett permanent ställe (s.k. schema location). ska samtidigt utgöra grundläggande s.k. namespace för xml-definitioner. Tidiga xml-definitioner som Sambruk skapade hade andra namespaces, såsom (med deras goda minne eftersom de delfinansierade tidiga projekt) eller olika varianter i kombination med Definitioner av detta slag är långsiktiga åtaganden men då möjlighet finns bör man successivt byta till namn enligt principen ovan. Eftersom namespace inte behöver finnas som fysisk adress utan endast som unikt namn är detta dock inte ett överhängande problem. Dock är det lämpligt att lagringsadress (schema location) för framtiden överensstämmer med namespace. Samtidigt bör man nämna att av prestanda/stabilitetsskäl är det inte lämpligt att vid varje schemaexekvering hämta schemat från Sambrukssajten.

7 7(9) Det bör poängteras att denna typen av lagringsadress är ett långsiktigt åtagande på kanske år eller mer, så namnet måste behållas konsekvent. I dagens publiceringssystem för Sambrukssajten, SiteVision, löses adressen genom ett s.k. alias som pekar på en bestämd yta inom sajten. Det normala för tekniska specifikationer av detta slag är att Sambruk definitivt inte vill hålla dem hemliga utan istället befordra deras användning öppet, så mycket som är möjligt. Därmed uppstår interoperabilitet och förhoppningsvis kan Sambruk påverka både standardisering, myndigheter och leverantörer att använda definitioner som är i samklang med vad vi önskar - förebildens makt. Skulle ändå i något undantagsfall access till dessa filer behöva begränsas, läs avsnittet Begränsad access nedan (då bortfaller förstås även lagring på den självklart öppna adressen 6. PRINCIPER FÖR För att på ett praktiskt sätt använda vårt ur dokumenthanteringssynvinkel sett enkla, men dock vettiga verktyg behöver några principer fastställas enligt nedan Huvudsaklig sajtstruktur Pågående Sambruksprojekt återfinns i meny på startsidan. När man klickat in på ett visst projekts yta visas projektbeskrivning, aktuella aktiviteter, kalender etc. Där visas också ett antal menyval i vänstermenyn, såsom möteshandlingar mm. Här ska även alltid återfinnas: o Utgåvor Härunder placeras det som levereras från projektet enligt principerna ovan och som ska vara öppet nåbart. När man klickar på detta val kommer man till en enkel fillagringsyta vilket gör arkiveringsmöjligheterna mycket flexibla och generella. Dock ställs det höga krav på konsekventa och beskrivande filnamn samt versionsinformation enligt avsnittet Detaljerade generella principer. Ett större antal småfiler skulle leda till oöverblickbarhet. Dessa ska packas ihop till zip-filer som ges beskrivande namn. o Utgåvor (internt material) Härunder placeras förstås det som levereras från projektet enligt principerna ovan och som icke ska vara öppet nåbart. Fillagringsytan hanteras i övrigt likadant som de öppna utgåvorna. Startsidans toppmeny innehåller valet Programvara. Därvid leds man till en yta där vi i text sammanhållet beskriver viktiga utgåvor av programvara inom Sambruk. Programvaran eller andra utgåvor återfinns dock inte i sig där, utan det finns istället

8 8(9) länkar in till projektytorna, där programvaran ligger i sitt rätta sammanhang. Startsidan innehåller även under Ramverk valet Begreppsmodell och Nyttomeddelanden. Därvid leds man på liknande sätt som för Programvara till en yta där vi sammanhållet beskriver viktiga utgåvor av Begreppsmodeller och Nyttomeddelanden inom Sambruk, samt referenser till andra organisationers liknande definitioner som vi använder. Utgåvorna återfinns dock inte i sig där, utan det finns istället länkar in till projektytorna, där utgåvorna ligger i sitt rätta sammanhang. Historiska Sambruksprojekts resultat nås genom menyvalet Arkiverade projekt på startsidan. o Under detta val återfinns en lista över projekten och om man klickar på ett sådant kommer man till samma struktur som beskrivs ovan för de pågående projekten o Viktigt är att denna yta utgör ett arkiv, inte en sajtdel med nyhetsvärde. Den får alltså inte rensas eller tas bort. Även om ett dokument bara skulle läsas en gång på tio år kan just detta läsande spara stora summor pengar ifall återanvändning då kan ske. Endast ifall legala gallringsregler skulle behöva tillämpas ska borttagning ske, men eftersom Sambruk är en ideell förening är detta inte troligt. Skulle det vid något enstaka tillfälle behöva lagras mycket stora mängder data från ett Sambruksprojekt får man pröva från fall till fall hur man ska göra. Om kapaciteten hos Sambrukssajten inte räcker till kan datat behöva lagras på något annat långsiktigt lagringsställe, t.ex. i molnet eller hos en kommun. Beskrivning och länk till detta ställe ska självklart finnas på Sambrukssajten, samt info om var användarnamn/lösenord e.dyl. deponerats inom Sambruk, hur eventuell fortlöpande betalning till lagringsstället ska fungera etc Begränsad access Eftersom det som levereras från Sambruksprojekt i form av utgåvor av dokument, programvaror mm ibland behöver skyddas enligt ramverket Sambruksgemensamt Material (SGM) eller av andra orsaker så behöver principer för begränsad access fastställas. Enligt själva sajtstrukturen som beskrivs ovan så förutsätts det att det finns sajtytor som benämns internt material. En icke-inloggad användare kommer inte åt en sådan yta, utan möts istället av en inloggningsruta. Detta accesskydd sköts av inbyggd funktionalitet i publiceringsverktyget för Sambrukssajten, SiteVision. För den närliggande användningen av Sambrukssajten används en förenklad rättighetsstruktur enligt följande: o En mindre krets av personer inom Sambruk får rolltilllhörighet med läsrättigheter att som inloggade komma åt allt internt material. o En ytterligare något mindre krets av personer inom Sambruk får rolltilllhörighet med uppdateringsrättigheter att som inloggade komma åt samt lägga in, uppdatera och radera allt internt material.

9 9(9) o Detta innebär att ifall inte någon av deltagarna i ett visst Sambruksprojekt ingår i en sådan krets så får de höra av sig till Sambruks projektsamordnare, verkställande tjänsteman eller webmastrar för att få ombesörjt att läsa eller lägga in utgåvor. Att ge en person rätt till rolltillhörighet avgörs av Sambruks projektsamordnare eller verkställande tjänsteman. Sambrukssajtens webmastrar hanterar användarnamn, lösenord och rolltilllhörigheter praktiskt sett. Längre fram är det troligt att vi har nytta av att tillämpa en rättighetsmatris enligt följande: Person Internt material projekt A Internt material projekt B Internt material projekt C... AAA Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt BBB Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt CCC Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt DDD Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt Ingen Läs Uppdaterings-rätt För närvarande väntar vi med denna mer avancerade rättighetshantering av resursskäl.