TDP003 Projekt: Egna datormiljön

Installationsmanual

Ni ska under kursen skapa en gemensam installationsmanual för hela klassen. Innan denna vill vi att ni i era grupper skapar ett internt dokument med det just ni behövde installera. Från dessa dokument kan ni samla all den information som grupperna har letat fram så att ni slutligen får en riktigt bra, gemensam installationsmanual. Se schemat för information om deadlines.

Syfte

Tanken med en installationsmanual är att skapa en förklaring till hur man sätter upp den utvecklingsmiljö som behövs för att skapa, ändra och köra systemet. Detta inkluderar till exempel verktyg för att skriva och köra kod och versionshantera projektet, samt hantera några enklare fel som kan uppstå när man installerar eller eventuellt använder dessa verktyg. Det är er uppgift att ta reda på vilka verktyg som kan behövas i projektet, och ni behöver installera dessa själv för att se hur man gör och vad som kan gå fel. Tänk på att man efter installation även behöver ett enkelt test för att se om installationen fungerade.

Målgrupp

Vilket dokument du än skriver är det viktigt att tänka på målgruppen. Dokumentet måste anpassas så att målgruppen förstår. Riktar du dig till studenter som läser datateknik räcker det t.ex. att säga "installera VirtualBox". Riktar du dig däremot till vanliga människor (ej datavetare) måste du skriva ett 10-sidors dokument med detaljerade anvisningar och skärmdumpar på varje steg både nedladdning och installation. Kanske måste du även komplettera med ett dokument som förklarar hur datorn startas, och ett som förklarar hur webbläsaren fungerar.

Installationsmanualernas målgrupp är en genomsnittlig gymnasieelev med dataintresse, mest spel. Låt oss kalla hen Kim. Kim vet vad Linux är och har det installerat även om Kim oftast använder Windows. Kim kan skriva enkla HTML-sidor, och använda ftp, men vet inte riktigt hur det fungerar. När saker går fel i Windows brukar Kim kunna hitta en bra inställning eller fil för att lösa det, men när det går fel i Linux vet Kim inte vad hen skall göra, utan frågar oftast en kompis som vet lite mer. Kim vill kunna installera och underhålla portfolion utan att ta hjälp av kompisar.

Gruppens dokument

Hur ni i er grupp väljer att ta anteckningar kring installationerna är upp till er. Det finns ingen mall eller några krav på denna. Det rekommenderas dock starkt att ni försöker följa kraven och riktlinjerna för den gemensamma manualen redan vid anteckningsstadiet för att så smidigt som möjligt kunna skapa den gemensamma manualen.

Gemensam installationsmanual

Baserat på gruppernas interna dokument ska ni skapa en gemensam installationsmanual för hela klassen.

Ni kommer bli inbjudna till repositoryt där manualen ska skapas ett par dagar efter att alla har registrerat sig i Webreg.

Detta repository innehåller källkodsfilerna för den gemensamma installationsmanualen. Under kursens gång ska ni bidra antingen till testerna eller till installationsmanualen (se schema).

Kom ihåg att sätta igång med den gemensamma installationsmanualen tidigt! Det är många som ska samarbeta. Börjar ni för sent blir det väldigt svårt att samarbeta bra! Det är klassens ansvar att se till att den gemensamma installationsmanualen blir gjord innan deadline på denna. Kommunikation kommer vara viktigt vid denna uppgift.

OBS: Alla i klassen ska (individuellt) bidra med någon icke-trivial förbättring av antingen den gemensamma installationsmanualen eller databas-testerna via Git.

Krav på manualen

• Dokumenten skall vara målgruppsanpassade så att respektive målgrupp kan installera och använda portfolion, och självständigt hantera vanligt förekommande fel.
• Tillvägagången skall visas med konkreta och förklarade exempel, kommandon och skärmdumpar.
• Systemkrav, programvarukrav och förutsättningar skall dokumenteras, och vanliga fel beskrivas.
• Installationsmanualen skall innehålla ett avsnitt om felsökning och underhåll. Beskriv hur nya projekt kan läggas till och hur gamla kan modifieras.

Riktlinjer för manualen

• Bilder/figurer ska ha förklarande figurtexter med nummer, och de ska refereras till i texten.
• Det skall finnas information om författare, datum, dokumentversion, projektnamn, kurs och totalt antal sidor (dessa saker är bra att ha med i en dokumentmall, t.ex. i sidhuvud/sidfot på varje sida).
• Inlämning sker som pdf skriven i LaTeX med höga krav på språk och tydlig layout. Korrekturläs. Använd flera rubriknivåer. Sätt tydliga relevanta rubriker. Använd bilder och figurer för att förtydliga eller exemplifiera det som beskrivs i text. Numrera figurer och tabeller och hänvisa i texten så bilden ingår i den röda tråden. Formatera konsekvent kod, filnamn, eller andra typer av nyckelord med en annan font. Infoga innehållsförteckning om det är motiverat utifrån sidantalet, färre än fem sidor behöver sällan förteckning, det är lätt hitta ändå.
• Exakt vad manualerna ska innehålla är med mening inte hårt specifierat. Fundera på vad manualerna måste innehålla för att vara kompletta, jämför med liknande manualer för andra produkter eller projekt. Målet med installationsmanualen är att en användare med lite kännedom om Linux-system ska kunna installera er portfolio på sitt system. Användarmanualen har som mål att en användare med grundläggande datorvana ska kunna använda sidan utan att behöva testa sig fram.

Exempel

Ett mindre exempel finns här.

Sidansvarig: Pontus Haglund
Senast uppdaterad: 2023-08-28