Produktteam och programvaruteam har ett gemensamt problem: dokumentation.
Produktdokumentation är manualer och guider som förklarar arbetsflödet och användargränssnittet för en produkt. Hur kan den vanliga användaren vara produktiv med den här produkten? I denna mening kan produktdokumentation användas för programvaruprodukter.
Programvarudokumentation avser den underliggande tekniken, förutsättningarna och de konfigurerbara egenskaperna hos en programvaruprodukt. Hur konfigurerar, övervakar, hostar och distribuerar IT-administratörerna programvaran för användarna? Den här typen av dokumentation är viktig, särskilt när flera versioner eller grenar läggs till i mixen.
På sätt och vis är produktdokumentation som att lära någon att köra bil. Hjulet vrider bilen, gaspedalen förflyttar bilen, bromspedalen stoppar bilen. Programvarudokumentation lär någon hur bilen fungerar. Hjulet är kopplat till framaxeln som vrider framdäcken 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 typerna av dokumentation är viktiga. Den ena utbildar användarna och den andra utbildar administratörer och utvecklare. Det är bra att visa människor hur man kör en bil, men om ingen vet hur bilen fungerar, vad händer då när bilen går sönder?
Mindre skillnader mellan produkt- och programvarudokumentation
Det finns mindre skillnader att vara medveten om när det gäller produkt- och programvarudokumentation:
Programvaru- och produktdokumentation: Målgrupp och personlighet
Produktdokumentation vänder sig till en enda målgrupp: användaren. Den utgår från att användaren inte har några tekniska kunskaper och kommunicerar på enkel engelska med minimal jargong. I likhet med en teknisk lärlingsutbildning jämfört med en universitetsexamen utbildar den människor i hur man gör saker och ting, med mindre fokus på teoretisk eller konceptuell kunskap.
Programvarudokumentation riktar sig till IT-administratörer, ingenjörer och utvecklare. Den omfattar programvarans utformning och arkitektur, instruktioner för installation av kommandoraden, API- och integrationsstöd, datahantering och rapportering, nätverkstopologi - i princip de kuggar som får maskinen att fungera. Dessa dokument utgör en enda sanningskälla (SSOT) som IT-personal kan hänvisa till när de övervakar och felsöker programvaran.
Programvaru- och produktdokumentation: Uppdateringsfrekvenser
Programvarudokumentation måste uppdateras konsekvent när nya commits läggs in i huvudutgivningskanalen. Programvarudokumentationen måste lyfta fram nya funktioner och kommandon och avskriva gamla funktioner. Nya eller förändrade beroenden bör dokumenteras, och funktionsstödet för alla målplattformar bör klargöras - t.ex. att en funktion fungerar på Windows, men inte på Linux.
Produktdokumentationen behöver bara uppdateras när underliggande programvaruändringar leder till en förändring av arbetsflödet eller användbarheten. En utvecklare ändrar koden för en betalningsgateway, men betalningsprocessen för användarna förblir densamma, så inga uppdateringar behövs.
Detta visar en naturlig hierarki för dokumentation av programvaruprodukter. Den tekniska programvarudokumentationen utgör grunden, och efterföljande produktdokumentation bygger på denna grund. Därför bör man fokusera på att göra bra programvarudokumentation, eftersom det ger upphov till ännu bättre produktdokumentation.
Exempel på ramar för formatering av produkt- och programvarudokumentation
En produktdokumentation kan följa denna ram:
-
Produktnamn
-
Översikt över produktens syfte*.
-
Inställningsguide
Feature 1 Förklaring och bilder
Feature 2 Förklaring och bilder
Kundsupportlänkar
På samma sätt skulle en programvarudokumentation kunna följa denna ram:
-
Programvarunamn
-
Översikt över programvarans syfte Oversikt över programvarans syfte Oversikt över programvarans syfte Oversikt över programvaran
Mjukvaruberoenden Mjukvaruberoenden
Installationsguide
Funktion 1 Förklaring och bilder
Funktion 2 Förklaring och bilder
Länkar till teknisk support
Det är uppenbart att dessa två typer av dokumentation är nära besläktade med varandra och följer en liknande struktur. Detta innebär att produkt- och programvaruteam har mycket att lära av varandra och mycket potential när de samarbetar kring dokumentation.
Produkt- och programvarudokumentationsteam kan komplettera varandra
Det finns starka likheter mellan produkt- och programvarudokumentation. Detta ger upphov till frågan: kan produkt- och programvaruteam arbeta tillsammans?
Ja, det kan de, och det bör de göra!
Programvaruteam förstår den tekniska jargongen och den underliggande tekniken. Produktteamen förstår vad användarna ser, vill ha och behöver, dvs. användarupplevelsen. Författare av programvarudokumentation kan ge detaljerad teknisk information och författare av produktdokumentation kan späda ut de tekniska detaljerna så att de kan användas av en lekmannapublik.
Föreställ dig att du försöker förklara något i lekmannatermer utan att ha den förståelse på hög nivå som krävs för att formulera något som en lekman skulle förstå. Det är vad som händer när produktdokumentation skapas före programvarudokumentation.
Vad är kvantmekanik? Schrödingers katt är förmodligen den första tanken i ditt huvud! 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 programvarudokumentation, sluta med bättre produktdokumentation i Docsie
Sammanfattningsvis finns det många fördelar med att använda programvarudokumentation som mall för efterföljande produktdokumentation. Programvarudokumentation bör fungera som en enda sanningskälla för IT-personal och produktdokumentationsförfattare. När den är skriven har produktdokumentationsförfattarna klarhet och förståelse för att förenkla och dela användarvänlig kunskap med kunderna, med teknisk vägledning för korrekturläsning och kvalitetssäkring.
Genom att börja med bra programvarudokumentation kan dina skribenter skapa ännu bättre produktdokumentation!
Börja skapa dokumentation som hjälper dina kunder att göra mer. Anmäl dig till vår startplan (forever free!) och leverera dokumentationsglädje med Docsie!