What style of documentation should product managers use in order to communicate the appropriate message?

Dokumentation är en av de viktigaste och mest underskattade komponenterna i alla open source-projekt, och den bör inte tas lätt på.

De flesta open source-projekt får inte tillräcklig uppmärksamhet, oftast eftersom upphovspersonerna inte är intresserade av, saknar förmågan eller tiden att skapa en effektiv dokumentationsmiljö för sitt API och sin produkt.

Även om din applikation är utmärkt kommer användarna inte kunna dra nytta av den om dokumentationen är bristfällig.

Om de ändå måste använda den av någon anledning, kommer de inte kunna göra det effektivt eller på det sätt du önskar.

Att lära sig skapa bra dokumentation kräver mycket arbete, liksom att regelbundet studera andra dokumentationsprojekt. Men tro mig - som någon som skapat mängder av dokumentation för Docsie - om du bygger kod som ska användas av andra än dig själv, särskilt om dessa personer är dina kunder, bör din produkt vara väldokumenterad, välformaterad och dynamiskt presenterad.

Vad är skillnaden mellan handledningar, guider, förklaringar och referenser?¶

Många tror felaktigt att dessa fyra begrepp betyder samma sak. De har dock olika betydelser. Dessa olika typer av dokumentation är viktiga och har några avgörande skillnader:

Handledningsdokumentation: Informationsbaserad dokumentation inriktad på utbildning.

Steg-för-steg-guider/Användarguider: Guidedokumentation visar hur man löser specifika problem genom en serie steg för att uppnå ett visst mål.

Förklarande dokumentation: Artikelliknande dokumentation som hjälper användaren/läsaren att få djupare förståelse för en produkt genom förklaringar och bakgrundskontext.

Referensdokumentation: Denna dokumentation informerar användaren om beskrivningar av olika nya funktioner och användningsområden. Denna typ kan vara mycket "rå" i form av utvecklardokumentation, men kan också översättas till mer användarvänliga versionsnoteringar som är lättare att förstå för slutanvändaren.

Skäl att producera högkvalitativ dokumentation¶

Innan vi fortsätter är det viktigt att förstå varför kompetent dokumentationsskrivande är ett mycket viktigt men underskattat behov i dagens samhälle. Tillgången till omfattande och välskriven dokumentation är ett av de viktigaste kriterierna för att uppnå bred användning, särskilt i open source-projekt där nästan alla handlingar är tillgängliga för allmänheten och där sådana aktiviteter spelar en avgörande roll för projektets framgång.

Låt oss titta på de viktigaste orsakerna till att skriva effektiv dokumentation.

Det skapar en bättre introduktionsupplevelse för dina kunder¶

När du ger tillräcklig dokumentation om din produkt till dina kunder hjälper du dem att känna sig mer bekväma med din produkt och skyddade av dess specifika riktlinjer. För att detta ska ske måste du:

1. Se till att din produktdokumentation är synlig och lättillgänglig, antingen via länkar i appen eller på en sökbar dokumentationsplattform.

2. Se till att den är välskriven och hjälper kunden att hitta sitt svar snabbt och enkelt

Ett tips är att skriva din dokumentation en gång, och den kommer att användas om och om igen när nya kunder kommer i kontakt med ditt företag.

Färre supportärenden som resultat¶

Kunder som läser och förstår din dokumentation är mer benägna att köpa din produkt. När kunder inte kan lista ut något kan det vara mycket frustrerande, och de kan börja skylla på din produkt.

Vissa kunder kontaktar omedelbart supportteamet om de stöter på problem, men om dokumentationen är attraktiv, lättillgänglig och begriplig kan de lösa sina egna problem utan att behöva konsultera dig, vilket i sin tur får dem att känna sig mer självständiga.

Det hjälper dig att stödja ditt eget team¶

En robust kunskapsbas kan också användas för att hjälpa dina egna teammedlemmar. Ditt interna team bör vara informerat om nya funktioner, planerade färdplaner, API-dokumentation och allt annat som är nödvändigt för att hålla alla uppdaterade.

Steg-för-steg-anvisningar för att skriva effektiv dokumentation¶

Att skriva dokumentationens innehåll och strukturera detta arbete är helt skilda uppgifter från att bestämma vilken ton som ska användas och hur man ser till att dokumentationen är begriplig. Enligt O'Reilly finns det 8 regler för bra dokumentation:

1. Skapa dokumentation som är inbjudande för läsaren.

2. Producera grundlig dokumentation som täcker alla områden av projektet.

3. Skapa material som är lätt att skumma igenom och förstå.

4. Skapa dokumentation som visar hur man använder produkten genom fallstudier.

5. Skriv dokumentation som innehåller upprepning där det är nödvändigt.

6. Skriv dokumentation som är aktuell.

7. Skriv dokumentation som är enkel att bidra till.

8. Skriv dokumentation som är lätt att hitta och förstå.

Dessa element handlar främst om innehållet. Nedan går vi igenom "hur" man strukturerar denna information i sex steg:

Bestäm vad du ska dokumentera¶

Ta dig tid att fundera över vilken typ av dokumentation du ska producera innan du börjar: är det en handledning, ett referensdokument, en instruktionsmanual eller en förklaring?

Observera att din produkts natur kommer att ha direkt påverkan på vilken typ av dokumentation du ansvarar för att skapa.

Skapa ett ramverk¶

Bygg först en grund för din dokumentation. Det kan vara något väldigt litet i början och kan bestå av bara några få grupper, men med tiden kommer hela plattformen du bygger på att börja växa i storlek och komplexitet. Du bör regelbundet se över din organisationsstruktur.

Kom ihåg att du är läraren och du är ytterst ansvarig för hur dina elever lär sig i din klass. De kommer att vägledas av dina instruktioner; ju mer tid du lägger på struktur, desto mer framgångsrika kommer dina elever att vara i sina ansträngningar.

Använd alltid bra multimedietekniker¶

Se till att du använder videor, teckningar och varierande stilar och integrerar dem direkt i din dokumentation. Docsie möjliggör inbäddning av alla dessa inom vår plattform för att göra denna process enklare.

De hjälper inte bara kunderna att bättre förstå informationen du förmedlar, utan de ger också fantastisk sökmotoroptimering som leder till fler högkvalitativa leads tack vare din dynamiska dokumentation.

Se till att den är sökbar¶

Det finns skillnader i sökfunktionerna på olika kunskapsbasplattformar - vissa erbjuder bara grundläggande sökning utan möjlighet att fördjupa sig i segment (vilket är tekniskt okej om du inte har tusentals filer), medan andra erbjuder frågealternativ som låter dig söka inte bara i dokument utan även i användarnamn.

Men en sak är avgörande: du bör använda ett verktyg som låter dig söka snabbt. En sökfunktion inbyggd i appen gör det enkelt att söka efter filer och få en förhandsvisning av dem utan att lämna appen.

Docsie låter dig ha dynamiskt sökbar navigering för lättillgänglig information.

Sträva ständigt efter att förbättra och uppdatera¶

Att skapa och använda dokument är svårt eftersom de snabbt glöms bort av personerna som skapade eller drog nytta av dem. Dokument möter också flera utmaningar under sin livstid.

Med tiden börjar mappstrukturen likna en kyrkogård, eftersom äldre dokumentation tenderar att hamna längre ner på skärmen.

Se därför till att gå igenom din gamla dokumentation och göra förbättringar, samt uppmuntra dina kollegor att göra detsamma då och då. Docsie låter dig skapa uppdateringar genom vårt avancerade versionssystem som är enkelt att använda.

Avslutande tankar:¶

Vill du veta mer om hur man skriver effektiv dokumentation? För professionella inom mjukvarudokumentation finns det massor av bloggar och information att hitta här.