https://jiragu.atlassian.net/wiki/spaces/M3​​ är en mall för en yta/site för hela lösningsdokumentationen, allt från arkitektur, förvaltning och projekt. Dokumentationen beskriver lösningen och ska underhållas löpande.

Mallen utgör en struktur för att man ska känna igen sig och hitta information på samma ställe i olika lösningar.

Mallen skall användas för lösningar inom GUSPP-förvaltningen, dvs både inom projekt eller förvaltning kring lösningar och applikationer. Primärt används den idag för att dokumentera arkitekturen för en lösning, både under införande (projekt) och efterkommande förvaltningsfas.

Mallens version finns angiven på ytan översiktssida Overview, i tabellen, raden Mall.

Alla Confluenceytor som rör lösningar är taggade med Label (kategori) Lösning för att lätt kunna sortera ut lösningar i Spaces - Confluence (atlassian.net)

Mallen är indelad i följande övergripande sidor. Alla delar är idag inte obligatoriska att använda vilket framgår i tabellen nedan.

Det är naturligtvis viktigt att dokumentationen är aktuell och korrekt. Därför ingår det i samtliga projekts och förvaltningspersonals uppgifter att rätta fel och ändra dokumentationen när lösningen ändras.

Lösningar är inte statiska utan förändras kontinuerligt. Därför är det viktigt att se dokumentationen som en del av lösningen och säkerställa att den hänger med i förändringen.

Tanken är därför att informationen ska vara levande

• Man startar i förstudie och fyller i så djupt man kan. Här kan as-is och to-be scenarier finnas med i olika stycken. Det kan också finnas olika varianter av lösningsförslag.

• Man utvecklar framförallt lösningsarkitekturen under projektets gång. Lösningar som förkastas flyttas till arkivsidan för att uppnå spårbarhet. I slutet av projektet kvarstår bara de implementerade lösningarna. As-is flyttas till arkivet, to-be ligger kvar men behöver ingen rubrik för “to-be”.

• Man påbörjar förvaltningsinformationen under projektet och dokumenterar löpande så att informationen växer fram successivt som en del av lösningen.

• Vid överlämning till förvaltning kontrolleras att deploymentdiagram och driftsinformation är korrekta.

• Dokumentationen underhålls löpande vid normalt systemunderhåll. Kommer nya målbilder om framtida lösningar, kan det vara aktuellt att införa as-is och to-be scenarios igen.

• Nya projekt som berör lösningen dokumenteras normalt i samma i Confluenceyta (space). Skapar man en helt ny lösning som ersätter den gamla skapar man en ny yta för den nya lösningen och arkiverar den gamla ytan när man pensionerat den gamla lösningen.

De flesta sidor har en liknande struktur. Nedan beskrivs de element som oftast ingår på en sida.

1. Sidans namn / titel

2. På varje sida infogas med fördel generell sidinformation.
   Sidinformationen läggs inom ett makro som heter Page properties, som gör att man kan hämta ut denna information och visa på andra sidor.

   

3. Under sidinformationen, placeras när det är tillämpligt en innehållsförteckning, här anges texten Innehållsförteckning (i formatet Normal) med fet stil. Och så infogas antingen innehållsförteckning för sidan, eller en lista över undersidor.
   Efter innehållsförteckningen placeras en linje - via makrot Divider.

4. Om sidan skall innehålla innehåll, läggs detta efter stycket och linjen enligt punkt 3 ovan.

5. Om det är tillämpbart, så kan man på slutet av sidan lägga in relaterat innehåll, via makrot Content by Label. I makrot anges man vilket/vilka labels man vill innehåll skall visas för. Se till att bocka ut “Show Labels for Each Page” och “Show Space Name for Each Page”.
   Se till att ha en linje - via makrot Divider ovanför Content by Label.

6. Längst ner på sidan till höger, visas eventuella Labels som är satta för sidan. Läs mer om hur man använder etiketter på Confluence hjälpsidor.

Administratörsrättigheter till ytan

Man bör ha en grupp (Group) som administrerar ytan/spacet.

Skrivrättigheter till ytan

Personer som arbetar inom arkitekturfunktionen, i projekt och förvaltning av lösningen, samt i objektet som lösningen tillhör, bör default alla kunna komma åt att skriva på ytan.

Läsrättigheter till ytan

Personer som arbetar inom arkitekturfunktionen, i projekt och förvaltning av lösningen, i objektet som lösningen tillhör, samt övrig personal som arbetar inom GUSPP, bör default alla kunna komma åt att läsa på ytan.

Enklast är att göra ytan läsbar för alla inloggade användare univeristets Confluencesajt, (dvs gruppen confluence-users).

Följande sidor skall underhållas för lösningen:

• Sidan Overview (ytans övergripande sidan)

• Alla sidor som är markerade som obligatoriska - de listas här ​​.

• Utöver de obligatoriska sidorna finns även, ett flertal sidor som är “frivilliga” att använda.
  Vilka alla dessa är listas på sidan ​​ .

Generella riktlinjer

• Omfattande information går bra att bryta ner i undersidor så länge som man länkar från rätt stycke på toppnivån.

• Ta inte bort sidor och rubriker, det ska gå att utläsa att man beaktat sidan eller stycket även när det saknas relevant information att fylla i. Skriv N/A eller en kort kommentar om varför information inte är relevant.

• Ta inte bort information om olika lösningsförlag - utan arkivera det. Information om hur man hanterar borttag kan man läsa under avsnittet https://jiragu.atlassian.net/wiki/spaces/M3/pages/2694710069#Ta-bort-information

Sidegenskaper

Högst upp på de flesta sidor, finns en ruta med något som kallas för sidegenskaper. Genom att fylla i information i denna ruta så kan man lista detta innehåll om flera olika sidor på en annan sida.

• Beskrivning: här fyller man i en kort beskrivning av vad sidan innehåller och syftar till.

• Skall vara ifylld *: här visas en statusetikett för om sidan anses vara FRIVILLIG eller OBLIGATORISK. Ändra inte innehållet i denna för sidor som kommer i mallen, utan låt det värde stå som finns på sidan.

  • Obligatorisk sida = sidan skall ha information eller länk till annan plats där informationen lagras. Att sidan är obligatorisk indikerar att detta är information som skall finnas beskriven om lösningen.

  • Frivillig sida = sidan är INTE obligatorisk - utan frivillig att använda. Om motsvarande information finns någon annanstans, så kan man med fördel länka till denna sida istället. Eller så kan man helt ta bort sidan om man vill. Det kan tex handla om information som inte är relevant för systemet, tex information kring underhållsrutiner om systemet driftas som en molntjänst.

• Lösning : här anges länken till själva ytan för lösningen, tex https://jiragu.atlassian.net/wiki/spaces/M3.

• Status på sidan: här skall det finnas en statusetikett som visar på sidans status. Ange /Status så hittar Confluence makrot statusetikett att infoga. Någon av följande statusar anges, gärna med dessa färgkoder också
  PUBLICERAD​ = sidan är publicerad
  AUTOMATISK = används på sidor som anses “färdiga” och publicerade redan av mallen
  PÅBÖRJAD​ = sidan är påbörjad men ännu inte helt klar för publicering
  BEHÖVER SES ÖVER​ = sidan är publicerad men behöver ses över
  ARKIVERAD​ = sidan är arkiverad (dvs inte längre aktuell)

Instruktionstext och exempel i mallen

Instruktionstext och exempel i mallen är definierade som informationsrutor likt denna:

Instruktionstext tas bort. Exempel ersätts med faktisk information utan informationsruta.

Värden som skall ersättas i mallen

Värden som ska ersättas med faktiskt information står mellan <>, till exempel < ange xx >.

As-is och To-Be

Om man har scenarior och lösningsförslag för inte bara nuläget (as-is) utan också för framtida målbilder - börläge - to-be, så kan det vara bra att även informera om as-is scenarios/lösningar.

Man kan med fördel placera as-is scenarios i makrot Expand, likt följande exempel

To-be scenarios som förkastas, flyttas till arkivet och as-is ligger kvar men behöver ingen rubrik för “as-is”.

När as-is scenarios implmenteras så kvarstår enbart dessa beskrivna, och As-is flyttas till arkivet,

Ta bort information

Använd etiketter (Label) på sidor

Information som behöver kompletteras eller inte stämmer