Teknik 1 · Kapitel 12

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

Vilken kommentar hjälper mest?

Versionshantering

Spara förändringar med sammanhang

Version 1→Ändring + beskrivning→Version 2→Fortsatt arbete

jämför versioner
se vem som ändrade vad
återställ ett tidigare läge
arbeta parallellt i grenar

Git och GitHub

Verktyg och samarbetsplattform

Git	GitHub
Versionshanteringssystem	Webbaserad tjänst för Git-repositorier
Kan användas lokalt	Lagrar och delar projekt online
Commit, branch och merge	Pull requests, granskning och ärenden

GitHub använder Git, men Git är inte samma sak som GitHub.

En bra commit

En begriplig förändring

Otydligt

fix

Tydligt

Rätta validering av tom e-postadress

En commit bör vara avgränsad och beskriva vad förändringen åstadkommer.

Presentation

Välj budskap före detaljer

Vad ska mottagaren förstå?
Vad behöver mottagaren besluta eller göra?
Vilka bevis och exempel behövs?
Vilka tekniska detaljer kan vänta?

En presentation är ett urval – inte all dokumentation uppläst.

Visuell kommunikation

Visa relationen som ska förstås

Flödesschema	Ordning och beslut
Systemdiagram	Komponenter och kopplingar
Skärmbild	Gränssnitt och visuellt resultat
Diagram	Mängder, förändring och jämförelse
Demonstration	Faktiskt beteende i användning

Förklara ett system

Från helhet till detalj

Problem och användare→Lösningens helhet→Viktiga delar→Resultat och begränsningar

Mottagaren behöver en karta innan de tekniska detaljerna blir begripliga.

Elevator pitch

Förklara nyttan på en minut

För [målgrupp] som har [problem] erbjuder vår lösning [funktion]. Den skapar [nytta], till skillnad från [alternativ].

Fokusera på problem, mottagare och värde – inte en lista över all teknik.

Interaktiv pitchbyggare

Formulera kärnan

Målgrupp Problem Lösning Nytta

Pitch

Fyll i fälten och skapa en pitch.

Webbplatsprojekt

Tre spår genom hela projektet

Kommunikation	Diskutera krav, design, status och problem.
Dokumentation	Beskriv struktur, dataflöden, kod och tester.
Presentation	Demonstrera webbplatsen och förklara nyttan.

Unity-projekt

Förklara både regler och upplevelse

Kommunikation	Samordna spelmekanik, nivåer, grafik och kod.
Dokumentation	Beskriv system, skript, tillgångar och testresultat.
Presentation	Visa spelet och demonstrera centrala funktioner.

Loggbok

Dokumentera arbetets utveckling

vad gjorde jag?
varför valde jag denna lösning?
vilka problem uppstod?
hur testades och förbättrades resultatet?
vad är nästa steg?

En bra loggbok beskriver beslut och lärande, inte bara en lista över aktiviteter.

Interaktivt beslut

Vilken dokumentation behövs?

En ny utvecklare ska underhålla en koppling mellan en webbplats och ett betalningssystem.

Praktisk övning

Dokumentera och presentera en lösning

Välj en teknisk lösning och två mottagare.
Skapa en enkel systembeskrivning.
Skriv en kort användarguide.
Förbättra namn och kommentarer i ett kodexempel.
Skapa en tydlig visuell modell.
Presentera lösningen på en minut.

Exit ticket

Tre frågor

Hur skiljer sig dokumentation från presentation?
När hjälper en kodkommentar – och när behövs tydligare kod?
Vad skiljer Git från GitHub?

Sammanfattning

Kom ihåg

Kommunikation skapar gemensam förståelse och samordning.
Dokumentation bevarar kunskap om system och beslut.
Tydlig kod och relevanta kommentarer kompletterar varandra.
Git hanterar versioner; GitHub stödjer lagring och samarbete.
En presentation anpassar budskap och detaljer till mottagaren.