Produktteam och mjukvaruteam har en gemensam utmaning: dokumentation¶

Produktdokumentation består av användarorienterade manualer och guider som förklarar arbetsflöden och användargränssnitt. Hur kan en genomsnittlig användare bli produktiv med produkten? I detta avseende kan produktdokumentation användas för mjukvaruprodukter.

Mjukvarudokumentation beskriver de underliggande teknologierna, förutsättningarna och konfigurerbara attributen hos en mjukvaruprodukt. Hur konfigurerar, övervakar, driftsätter och distribuerar IT-administratörer mjukvaruprodukten till användarna? Denna typ av dokumentation är särskilt viktig när flera versioner eller grenar läggs till.

Produktdokumentation kan liknas vid att lära någon köra bil. Ratten styr bilen, gaspedalen får bilen att röra sig, bromspedalen stannar bilen. Mjukvarudokumentation lär istället ut hur bilen fungerar. Ratten är kopplad till framaxeln som styr framhjulen för att ändra färdriktningen; gaspedalen ökar luftflödet till motorn som drar in mer bränsle, vilket genererar vridmoment och hästkrafter.

Båda dokumentationstyperna är viktiga. Den ena utbildar användare, den andra utbildar administratörer och utvecklare. Det är bra att visa folk hur man kör en bil, men om ingen vet hur bilen fungerar, vad händer när bilen går sönder?

Mindre skillnader mellan produkt- och mjukvarudokumentation¶

Det finns några mindre skillnader att vara medveten om gällande produkt- och mjukvarudokumentation:

Mjukvaru- och produktdokumentation: Målgrupp och persona¶

Produktdokumentation riktar sig till en enda målgrupp: användaren. Den förutsätter att användaren saknar teknisk kunskap och kommunicerar på enkelt språk med minimal jargong. Precis som ett tekniskt lärlingsskap jämfört med en universitetsutbildning fokuserar den på hur man gör saker, med mindre tonvikt på teoretisk eller konceptuell kunskap.

Mjukvarudokumentation riktar sig till IT-administratörer, ingenjörer och utvecklare. Den täcker mjukvarans design och arkitektur, kommandoradsbaserade installationsinstruktioner, API- och integrationsstöd, datahantering och rapportering, nätverkstopologi – i princip alla kugghjul som får maskinen att fungera. Dessa dokument utgör en enda sanningskälla (SSOT) som IT-personal kan använda vid övervakning och felsökning av mjukvaruapplikationen.

Mjukvaru- och produktdokumentation: Uppdateringsfrekvens¶

Mjukvarudokumentation måste uppdateras kontinuerligt när nya commits slås samman i huvudversionen. Mjukvarudokumentationen måste lyfta fram nya funktioner och kommandon och avveckla gamla funktioner. Nya eller förändrade beroenden bör dokumenteras, och funktionsstöd för alla målplattformar bör klargöras – exempelvis att en funktion fungerar på Windows men inte på Linux.

Produktdokumentation behöver bara uppdateras när underliggande mjukvaruändringar utlöser en förändring i arbetsflöde eller användbarhet. Om en utvecklare ändrar koden för en betalningsgateway, men betalningsprocessen för användarna förblir densamma, behövs inga uppdateringar.

Detta visar en naturlig hierarki för mjukvaruproduktdokumentation. Teknisk mjukvarudokumentation utgör grunden, och efterföljande produktdokumentation bygger på denna grund. Därför bör fokus ligga på att skapa bra mjukvarudokumentation, eftersom det leder till ännu bättre produktdokumentation.

Exempel på formateringsramverk för produkt- och mjukvarudokumentation¶

En produktdokumentation kan följa detta ramverk:

• Produktnamn
• Översikt över produktens syfte
• Installationsguide
• Förklaring och bilder för funktion 1
• Förklaring och bilder för funktion 2
• Länkar till kundsupport

På liknande sätt kan en mjukvarudokumentation följa detta ramverk:

• Mjukvarunamn
• Översikt över mjukvarans syfte
• Mjukvaruberoenden
• Installationsguide
• Förklaring och bilder för funktion 1
• Förklaring och bilder för funktion 2
• Länkar till teknisk support

Tydligt är att dessa två dokumentationstyper är nära besläktade och följer en liknande struktur. Detta innebär att produkt- och mjukvaruteam har mycket att lära av varandra och stor potential när de samarbetar kring dokumentation.

Produkt- och mjukvarudokumentationsteam kan komplettera varandra¶

Det finns tydliga likheter mellan produkt- och mjukvarudokumentation. Detta väcker frågan: kan produkt- och mjukvaruteam arbeta tillsammans?

Ja, det kan de, och det bör de!

Mjukvaruteam förstår den tekniska jargongen och de underliggande teknologierna. Produktteam förstår vad användarna ser, vill ha och behöver – användarupplevelsen. Mjukvarudokumentationsförfattare kan tillhandahålla detaljerad teknisk information, och produktdokumentationsförfattare kan förenkla de tekniska detaljerna för konsumtion av en lekmannapublik.

Föreställ dig att försöka förklara något i lekmannatermer utan att ha den djupa förståelse som krävs för att formulera något begripligt för en lekman. Det är vad som händer när produktdokumentation skapas innan mjukvarudokumentation.

Vad är kvantmekanik? Schrödingers katt är förmodligen det första som dyker upp i huvudet! Men vad har kvantmekanik med katter att göra? För användaren är det inte viktigt. För en fysiker betyder det allt.

Börja med mjukvarudokumentation, avsluta med bättre produktdokumentation i Docsie¶

Sammanfattningsvis finns det många fördelar med att använda mjukvarudokumentation som mall för efterföljande produktdokumentation. Mjukvarudokumentation bör fungera som en enda sanningskälla för IT-personal och produktdokumentationsförfattare. När den är skriven får produktdokumentationsförfattare den tydlighet och förståelse som behövs för att förenkla och dela användarvänlig kunskap med kunder, med teknisk vägledning för korrekturläsning och kvalitetssäkring.

Enkelt uttryckt, genom att börja med bra mjukvarudokumentation kan dina författare skapa ännu bättre produktdokumentation!

Börja skapa dokumentation som hjälper dina kunder att göra mer. Registrera dig för vår Startup-plan (gratis för alltid!) och leverera dokumentationsglädje med Docsie!