Teknik 2 · Kapitel 23

Kommunikation, dokumentation och presentation

Tekniska lösningar behöver kunna förstås, användas och utvecklas av andra.

Lektionsmål

Efter kapitlet ska du kunna...

förklara varför kommunikation behövs i tekniska projekt
välja relevant dokumentation för olika syften
använda kodkommentarer och versionshantering klokt
presentera en teknisk lösning tydligt för en mottagare

Startfråga

Om bara du förstår lösningen

Kan någon annan använda den?

Kan teamet felsöka den?

Kan projektet fortsätta när du är borta?

Begriplighet är en del av teknikens kvalitet.

Tre uppgifter

Liknande – men inte samma

Kommunikation	Dela information och samordna arbete.
Dokumentation	Bevara kunskap om system och beslut.
Presentation	Förklara en utvald helhet för en mottagare.

Kommunikation

Skapa en gemensam bild

vad är målet?
vad har beslutats?
vem ansvarar för vad?
vilka hinder finns?
vad behöver hända härnäst?

Bra kommunikation minskar antaganden och gör avvikelser synliga tidigt.

Kommunikationskanaler

Välj kanal efter uppgift

Möte	Diskussion, beslut och komplexa frågor
Chatt	Snabba frågor och kort samordning
Dokument	Beständig och strukturerad information
Projektverktyg	Uppgifter, ansvar, status och deadlines
Kodkommentar	Förklaring nära den tekniska detaljen

Digitala verktyg

Verktyget löser inte samarbetet

TrelloJiraSlackDiscordDelade dokumentGitHub

Teamet behöver fortfarande regler för var beslut, uppgifter och dokument ska finnas.

Mottagare

Samma teknik – olika förklaring

Mottagare	Behöver främst förstå
Användare	Hur lösningen används säkert och effektivt
Utvecklare	Struktur, dataflöden, gränssnitt och beslut
Beställare	Nytta, kostnad, risk och resultat
Testare	Krav, testmiljö och förväntat beteende

Dokumentation

Projektets gemensamma minne

Dokumentation beskriver hur systemet fungerar, varför beslut togs och hur arbetet genomfördes.

gör kunskap sökbar
stödjer underhåll och felsökning
hjälper nya personer in i projektet
gör beslut möjliga att följa upp

Dokumenttyper

Dokumentera rätt sak

Projektplan	Mål, tid, resurser och ansvar
Systembeskrivning	Komponenter, relationer och dataflöden
Teknisk rapport	Metod, resultat, problem och slutsatser
Testprotokoll	Testfall, förväntat resultat och utfall
Användarguide	Hur lösningen används

Bra dokumentation

Tillräcklig och aktuell

har ett tydligt syfte och en mottagare
finns där teamet förväntar sig
använder gemensamma begrepp
uppdateras när systemet förändras
är tillräckligt detaljerad utan att duplicera allt

Dokumentationsskuld

Fel information kan vara värre än ingen

Om dokumentationen inte uppdateras kan teamet fatta beslut utifrån ett system som inte längre finns.

System ändras→Dokumentet lämnas→Fel antaganden→Nya problem

Kodkommentarer

Förklara det koden inte säger

# Fel: beskriver bara raden
antal = antal + 1  # Öka antal med ett

# Bättre: förklarar orsaken
antal = antal + 1  # Första posten har index 0

Kommentera främst varför en oväntad lösning eller ett antagande behövs.

Självdokumenterande kod

Tydliga namn minskar behovet av kommentarer

x = s / n

Kort men otydligt.

medelvarde = summa / antal

Namn visar avsikten.

Kommentarer ska komplettera tydlig kod – inte försöka rädda otydlig kod.

Kontrollfråga