Vilken typ av dokumentation bör produktcheferna använda för att kommunicera rätt budskap?

Dokumentation är en av de viktigaste och mest underskattade komponenterna i alla projekt med öppen källkod, och den bör inte tas lättvindigt.

Generellt sett får de flesta projekt med öppen källkod inte tillräcklig uppmärksamhet helt enkelt därför att deras författare inte är riktigt intresserade av, är oförmögna att eller inte har tid att skapa en effektiv dokumentationsmiljö för sin API- och produktdokumentation.

Även om din tillämpning kan vara utmärkt, kommer konsumenterna inte att kunna dra nytta av den om dokumentationen är otillräcklig.

Men även om de av någon anledning inte har något annat val än att använda den, kommer de inte att kunna göra det på ett framgångsrikt sätt eller på det sätt som du vill att de ska göra.

Att förstå hur man producerar utmärkt dokumentation kräver en betydande mängd arbete, liksom att regelbundet granska andra dokumentationsprojekt. Men ta mitt ord för det - som någon som har skapat en uppsjö av dokumentation för Docsie - om du bygger kod som kommer att användas av någon annan än dig själv, och särskilt om dessa personer är dina kunder, bör din produkt vara väldokumenterad, formaterad och dynamiskt presenterad.

Vad är skillnaden mellan handledning, hur man gör, förklaringar och referenser?

Många människor tror felaktigt att de fyra fraserna avser samma sak. De uttrycker dock en mängd olika betydelser. Dessa olika typer av dokumentationer är ganska viktiga och har några viktiga skillnader:

Undervisningsdokumentation: Dessa typer av dokumentation är informationsbaserad dokumentation som är inriktad på utbildning.

How-To Guides/User Guides Dokumentation: Användarhandledningar: Dokumentationer uttrycker hur man löser specifika problem genom en serie steg för att uppnå ett specifikt mål.

Dokumentation med förklaringar: Detta är dokumentation av artikeltyp som är utformad för att hjälpa användaren/läsaren att få en djupare förståelse för en produkt genom olika förklaringar och bakgrundssammanhang.

Dokumentation med referensnoter: Denna dokumentation är utformad för att informera användaren om beskrivningen av olika uppdateringar av nya funktioner och användningsområden. Denna typ av dokumentation kan vara mycket "rå" i form av dokumentation för utvecklare, men den kan också översättas till mer användarvänliga versionsnotiser som lätt kan förstås av slutanvändaren.

Skäl för att producera dokumentation av hög kvalitet

Innan vi fortsätter är det viktigt att förstå varför kompetent dokumentationsskrivning ä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å en omfattande användning, särskilt i projekt med öppen källkod där praktiskt taget alla åtgärder är tillgängliga för allmänheten och där sådan verksamhet spelar en avgörande roll för projektets framgång.

Låt oss ta en titt på de viktigaste skälen till att skriva effektiv dokumentation.

Det gör att du kan skapa en bättre onboarding-upplevelse för dina kunder.

När du tillhandahåller adekvat dokumentation om din produkt till dina kunder hjälper du dem genom att få dem att känna sig mer bekväma med din produkt och skyddade av dess specifika riktlinjer. Du måste göra följande för att detta ska kunna ske:

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

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

Ett råd är att skriva din dokumentation bara en gång, så kommer den att smältas om och om igen när nya kunder tas ombord av ditt företag.

Som en följd av detta blir det färre supportförfrågningar.

Kunder som läser och förstår din dokumentation är mer benägna att köpa dina varor. När kunderna inte kan räkna ut något kan det vara ganska irriterande, och de kan börja skylla på din produkt i stället.

Vissa kunder kanske omedelbart kontaktar eller skickar e-post till supportpersonalen om de stöter på ett problem, men om dokumentationen är attraktiv, lättillgänglig och begriplig kommer de att kunna lösa sina egna problem utan att behöva rådgöra med dig, vilket i sin tur gör att de känner sig mer kompetenta.

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. Så ditt interna team bör informeras om nya funktioner, planerade färdplaner, API-dokumentation och allt annat som är nödvändigt för att hålla alla på samma sida.

Steg-för-steg-instruktioner om hur man skriver effektiv dokumentation.

Att skriva innehållet i dokumentet och arrangera denna aktivitet är två helt skilda uppgifter från att bestämma vilken ton man ska använda och hur man ser till att dokumentationen blir begriplig. Enligt [O'Reilly finns det 8 regler för utmärkt dokumentation] (https://www.oreilly.com/content/the-eight-rules-of-good-documentation/):

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

2. Gör en grundlig dokumentation som täcker alla områden av projektet.

3. Förbered ett lättfattligt material som är lätt att förstå.

4. Skapa dokumentation som visar hur produkten kan användas genom fallstudier.

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

6. Skriv dokumentation som är uppdaterad.

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

8. Skriv dokumentation som är enkel att upptäcka och förstå.

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

Ta ett beslut om vad du ska registrera.

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

Observera att din produkts karaktär kommer att ha en direkt inverkan på vilken typ av dokumentation du kommer att vara ansvarig för att skapa.

Skapa ett ramverk.

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

Tänk på att du är läraren och att du i slutändan är ansvarig för hur dina elever lär sig i din klass. De kommer att styras av dina anvisningar; ju mer tid du lägger ner på struktur, desto mer framgångsrika kommer dina elever att vara i sina ansträngningar.

Utnyttja alltid sunda multimediatekniker.

Se till att du använder dig av videor, teckningar och varierande stilar och kopplar in dem direkt i din dokumentation. Docsie gör det möjligt att bädda in någon av dessa i vår plattform för att underlätta denna process.

De kommer inte bara att hjälpa konsumenterna att bättre förstå den information du uttrycker, utan de kommer också att ge en fantastisk sökmotoroptimering som kommer att leda till ett större antal högkvalitativa leads som ett resultat av din dynamiska dokumentation.

Se till att den är sökbar.

Det finns skillnader i sökmöjligheterna hos olika plattformar för kunskapsdatabaser - vissa av dem erbjuder endast grundläggande sökning utan möjlighet att göra segmenteringar (vilket tekniskt sett är okej om du inte har tusentals filer), medan andra erbjuder sökalternativ som gör det möjligt att söka inte bara i dokument utan även i användarnamn.

Det finns dock en sak som är avgörande: du bör använda ett verktyg som gör att du kan söka snabbt. En sökfunktion som ingår i appen gör det enkelt att söka efter filer och få en förhandsgranskning av dem utan att lämna appen.

Docsie gör det möjligt att ha dynamiskt sökbar navigering för lättillgänglig information.

Ständigt sträva efter att förbättra och uppdatera

Det är svårt att skapa och använda dokument eftersom de snabbt glöms bort av de personer som skapade dem eller drog nytta av dem. Dokumenten står också inför ett antal utmaningar under sin resa.

Med tiden får mappstrukturen ett utseende som en kyrkogård, eftersom äldre dokumentation tenderar att ligga kvar på en lägre plats på skärmen.

Se därför till att gå tillbaka till din gamla dokumentation och göra förbättringar, samt uppmuntra dina kollegor att göra detsamma från tid till annan. Docsie låter dig skapa uppdateringar genom vårt avancerade versioneringssystem som är enkelt och lätt att göra.

Avslutande tankar:

Vill du veta mer om hur man skriver effektiv dokumentation? Det finns massor av bloggar och information för dokumentationsansvariga inom programvaruområdet här.