Åtgärder

Skillnad mellan versioner av "Dokumentation"

Från DAU-handboken

 
(14 mellanliggande versioner av 5 användare visas inte)
Rad 1: Rad 1:
== Dokumentation ==
== Varför behövs dokumentation? ==


För återanvändning av forskningsdata är det viktigt att det finns tillräckligt med tillhörande dokumentation för att en sekundäranvändare ska kunna avgöra om data är intressanta eller ej. Det är svårt att exakt säga vad som är tillräckligt eftersom det varierar beroende på bl.a. disciplin, det specifika forskningsprojektet och typ av data. En vägledning till detta kommer att finnas i DAU-handboken, men det är upp till varje DAU att bedöma om data har den dokumentation som är nödvändig för återanvändning. Dokumentation kan t.ex. vara i form av en kortare sammanfattning/abstract, men också som forskningsrapporter, artiklar och metodbeskrivningar.
För att en sekundäranvändare ska kunna avgöra om data är intressanta eller ej är det viktigt att det finns tillräckligt med tillhörande dokumentation. Det är upp till dig som DAU-medarbetare att bedöma huruvida inkomna data har den dokumentation som behövs. Det är svårt att exakt säga vad som är tillräckligt eftersom det varierar beroende på bland annat det specifika forskningsprojektet, vilket ämnesområde det gäller och typ av data. Dokumentation kan t.ex. vara i form av en kortare sammanfattning/abstract, men också som bifogade forskningsrapporter, artiklar och metodbeskrivningar.


I många fall används ''dokumentation'' och ''metadata'' som synonyma begrepp. Gränserna mellan dem kan ibland vara flytade, men det finns skillnader. Dokumentationen riktas i första hand till människor och kan bestå av löpande text, medan metadata är ordnade för att också kunna läsas av datorer. Eftersom dokumentationen inte behöver vara maskinläsbar har den inte samma krav på struktur som metadata.
I många fall används ''dokumentation'' och ''metadata'' som synonyma begrepp. Gränserna mellan dem kan ibland vara flytande, men det finns skillnader. Dokumentationen riktas i första hand till människor och kan bestå av löpande text, medan metadata är ordnade för att också kunna läsas av datorer. Eftersom dokumentationen inte behöver vara maskinläsbar har den inte samma krav på struktur som metadata.


För att forskningsdata ska kunna återanvändas är det många detaljer som behöver dokumenteras under ett forskningsprojekt. Några exempel på sådant som forskare bör dokumentera är:
Några exempel på sådant som bör dokumenteras är:


* innehåll i datafilen, t.ex. variabellista eller kodbok
* frågeställningar och syftet med studien
* frågeställningar och syftet med studien
* en beskrivning av vald insamlingsmetod
* en beskrivning av vald insamlingsmetod
* en överblick över analysarbetet
* en överblick över analysarbetet
* en beskrivning av de data som används för analys
* en beskrivning av de data som används för analys
* hur olika filer hänger ihop
* hur olika filer hänger ihop.


Se [[Kontroll av inkommande data|Kontroll av inkommande data]] för mer information.
Läs mer om hur man praktiskt granskar dokumentation på [[Kontroll av data]]
 
== Exempel på dokumentation ==
 
Några exempel på vilken dokumentation skulle behövas för olika [[datatyper]]:
 
'''Tabelldata''': Här är det viktigt att varje variabel/kolumn är tydligt beskriven. Ofta används förkortningar som header för varje kolumn i en tabelldatabas, och det är viktigt att dessa förkortningar förklaras med en kort beskrivning (det kan räcka med ett fullständigt alternativ till en förkortning som används som kolumn-header, t.ex. ’CORINE 2012 Land cover type code’ istället för ’COR_TYPE’). En annan sak man ska kolla är att varje variabel/kolumn är ifylld på samma sätt. T.ex. alla datum i en kolumn som heter 'date of sampling' ska ha samma format.
 
'''Bilder''': En stor samling bilder kan behöva dokumenteras på olika sätt, och mycket dokumentation kan också räknas som metadata. Det är viktigt att bilderna har tydliga filnamn. Filnamnen kan t.ex. vara en beskrivning av bilden eller en kod som kan tolkas med hjälp av en kodlista. Om bilderna är uppdelade i olika mappar är det viktigt att mappstrukturen är tydlig och att varje mapp har namngetts på ett sätt som gör det enkelt att navigera och förstå innehållet i olika mappar.
 
'''Geospatiala data''': Här förväntar man sig en förklaring av innehållet av de data som lämnas in. Dokumentationen kan finnas som en del av datamaterialet eller som separata textfiler. Det kan vara svårt att öppna spatiala data och kolla att all information finns för att kunna förstå datamaterialet, så det är viktigt att kommunicera med forskaren för att försäkra sig om att datamaterialet går att använda med dess befintliga dokumentation. Några saker man kan fråga om är:
# Finns det information om projektion och koordinatsystem?
# Finns det kolumndata som behöver tydligt beskrivas (spatiala data kan innehålla kolumndata)?
 
 
=== Use cases ===
'''1) Mätningar på atmosfärshalter av olika växthusgaser''' 
 
Data består av: Tabelldata (en tabellfil med flera kolumner/fält)
 
Det är viktigt att för återanvändaren att förstå vad varje fält/kolumn i datafilen beskriver, och i vilka enheter. Ett bra sätt att dokumentera den här typen av data kan vara att ladda upp en variabellista som beskriver kolumnerna i tabelldatafilen, att bifoga en artikel som beskriver kolumnerna, eller att dokumentera dem direkt i datafilen.
 
'''2) Data från en arkeologisk undersökning'''
 
Data består av: Utgrävningsdatabas (en databas med flera tabeller som innehåller information om olika typer av fynd, arkeologiska lager, bildbeskrivningar, m.m.) och bilder (inscannade kartor, fotografier från utgrävningarna, fotografier på fynd, m.m.).
 
Väldigt viktigt att förstå innehållet i databasen genom tabell och fältbeskrivningar, samt att kunna förstå hur (om) bilderna kopplas till utgrävningsdatabasen, genom en variabellista, kodbok, eller motsvarande. Utgrävningar ofta har ett antal opublicerade rapporter som slutprodukt. Det är viktigt att de (eller ett relevant urval) följer med som dokumentation. Fältdagböcker och annat material kan eventuellt också tillgängliggöras som dokumentation.

Nuvarande version från 21 februari 2022 kl. 07.32

Varför behövs dokumentation?

För att en sekundäranvändare ska kunna avgöra om data är intressanta eller ej är det viktigt att det finns tillräckligt med tillhörande dokumentation. Det är upp till dig som DAU-medarbetare att bedöma huruvida inkomna data har den dokumentation som behövs. Det är svårt att exakt säga vad som är tillräckligt eftersom det varierar beroende på bland annat det specifika forskningsprojektet, vilket ämnesområde det gäller och typ av data. Dokumentation kan t.ex. vara i form av en kortare sammanfattning/abstract, men också som bifogade forskningsrapporter, artiklar och metodbeskrivningar.

I många fall används dokumentation och metadata som synonyma begrepp. Gränserna mellan dem kan ibland vara flytande, men det finns skillnader. Dokumentationen riktas i första hand till människor och kan bestå av löpande text, medan metadata är ordnade för att också kunna läsas av datorer. Eftersom dokumentationen inte behöver vara maskinläsbar har den inte samma krav på struktur som metadata.

Några exempel på sådant som bör dokumenteras är:

  • innehåll i datafilen, t.ex. variabellista eller kodbok
  • frågeställningar och syftet med studien
  • en beskrivning av vald insamlingsmetod
  • en överblick över analysarbetet
  • en beskrivning av de data som används för analys
  • hur olika filer hänger ihop.

Läs mer om hur man praktiskt granskar dokumentation på Kontroll av data

Exempel på dokumentation

Några exempel på vilken dokumentation skulle behövas för olika datatyper:

Tabelldata: Här är det viktigt att varje variabel/kolumn är tydligt beskriven. Ofta används förkortningar som header för varje kolumn i en tabelldatabas, och det är viktigt att dessa förkortningar förklaras med en kort beskrivning (det kan räcka med ett fullständigt alternativ till en förkortning som används som kolumn-header, t.ex. ’CORINE 2012 Land cover type code’ istället för ’COR_TYPE’). En annan sak man ska kolla är att varje variabel/kolumn är ifylld på samma sätt. T.ex. alla datum i en kolumn som heter 'date of sampling' ska ha samma format.

Bilder: En stor samling bilder kan behöva dokumenteras på olika sätt, och mycket dokumentation kan också räknas som metadata. Det är viktigt att bilderna har tydliga filnamn. Filnamnen kan t.ex. vara en beskrivning av bilden eller en kod som kan tolkas med hjälp av en kodlista. Om bilderna är uppdelade i olika mappar är det viktigt att mappstrukturen är tydlig och att varje mapp har namngetts på ett sätt som gör det enkelt att navigera och förstå innehållet i olika mappar.

Geospatiala data: Här förväntar man sig en förklaring av innehållet av de data som lämnas in. Dokumentationen kan finnas som en del av datamaterialet eller som separata textfiler. Det kan vara svårt att öppna spatiala data och kolla att all information finns för att kunna förstå datamaterialet, så det är viktigt att kommunicera med forskaren för att försäkra sig om att datamaterialet går att använda med dess befintliga dokumentation. Några saker man kan fråga om är:

  1. Finns det information om projektion och koordinatsystem?
  2. Finns det kolumndata som behöver tydligt beskrivas (spatiala data kan innehålla kolumndata)?


Use cases

1) Mätningar på atmosfärshalter av olika växthusgaser

Data består av: Tabelldata (en tabellfil med flera kolumner/fält)

Det är viktigt att för återanvändaren att förstå vad varje fält/kolumn i datafilen beskriver, och i vilka enheter. Ett bra sätt att dokumentera den här typen av data kan vara att ladda upp en variabellista som beskriver kolumnerna i tabelldatafilen, att bifoga en artikel som beskriver kolumnerna, eller att dokumentera dem direkt i datafilen.

2) Data från en arkeologisk undersökning

Data består av: Utgrävningsdatabas (en databas med flera tabeller som innehåller information om olika typer av fynd, arkeologiska lager, bildbeskrivningar, m.m.) och bilder (inscannade kartor, fotografier från utgrävningarna, fotografier på fynd, m.m.).

Väldigt viktigt att förstå innehållet i databasen genom tabell och fältbeskrivningar, samt att kunna förstå hur (om) bilderna kopplas till utgrävningsdatabasen, genom en variabellista, kodbok, eller motsvarande. Utgrävningar ofta har ett antal opublicerade rapporter som slutprodukt. Det är viktigt att de (eller ett relevant urval) följer med som dokumentation. Fältdagböcker och annat material kan eventuellt också tillgängliggöras som dokumentation.