Användardokumentation: vad gör det dåligt och hur man fixar det

Programvarudokumentation är bara en uppsättning artiklar. Men även de kan göra dig galen. För det första spenderar du lång tid på att leta efter de nödvändiga instruktionerna. Då förstår du den oklara texten. Du gör som skrivet, men problemet är inte löst. Du letar efter en annan artikel, du blir nervös... En timme senare ger du upp allt och går. Det är så dålig dokumentation fungerar. Vad gör det så här och hur man fixar det – läs under snittet.

Det fanns många brister i vår gamla dokumentation. Vi har arbetat om det i nästan ett år nu så att scenariot som beskrivs ovan inte påverkar våra kunder. Se, som det var и hur hände det.

Problem 1: Otydliga, dåligt skrivna artiklar

Om dokumentationen är omöjlig att förstå, vad är poängen med den? Men ingen skriver obegripliga artiklar med flit. De händer när författaren inte tänker på publiken och syftet, häller vatten och inte kontrollerar texten för fel.

• Publiken. Innan du skriver en artikel måste du tänka på läsarens förberedelsenivå. Det är logiskt att du i en artikel för en nybörjare inte ska hoppa över de grundläggande stegen och lämna tekniska termer utan förklaring, men i en artikel om en sällsynt funktion som bara proffs behöver, bör du förklara innebörden av ordet PHP.
• Mål. En sak till att tänka på i förväg. Författaren måste sätta upp ett tydligt mål, bestämma den användbara effekten av artikeln och bestämma vad läsaren ska göra efter att ha läst den. Om detta inte görs kommer du att få beskrivning för beskrivningens skull.
• Vatten och insekter. Det finns mycket onödig information och byråkrati, fel och stavfel stör uppfattningen. Även om läsaren inte är grammatiknazist kan slarv i texten stänga av honom.

Tänk på tipsen ovan så blir artiklarna tydligare - garanterat. För att göra det ännu bättre, använd vår 50 frågor när du arbetar med teknisk dokumentation.

Problem 2. Artiklar svarar inte på alla frågor

Det är dåligt när dokumentationen inte hänger med i utvecklingen, inte svarar på riktiga frågor och fel i den inte korrigeras på flera år. Detta är inte så mycket problem för författaren, utan om organisationen av processer inom företaget.

Dokumentation hänger inte med i utvecklingen

Funktionen är redan i release, marknadsföring planerar att täcka den, och sedan visar det sig att den nya artikeln eller översättningen fortfarande inte finns i dokumentationen. Vi var till och med tvungna att skjuta upp releasen på grund av detta. Du kan be alla att lämna över uppgifter till tekniska skribenter i tid så mycket du vill, men det kommer inte att fungera. Om processen inte är automatiserad kommer situationen att upprepa sig.

Vi har gjort ändringar i YouTrack. Uppdraget att skriva en artikel om en ny funktion faller på den tekniska skribenten i samma ögonblick som funktionen börjar testas. Sedan lär sig marknadsföring om det för att förbereda sig för marknadsföring. Aviseringar kommer också till Mattermost företagsbudbärare, så det är helt enkelt omöjligt att missa nyheter från utvecklare.

Dokumentationen återspeglar inte användarnas önskemål

Vi är vana vid att arbeta så här: en funktion kom ut, vi pratade om den. Vi beskrev hur man slår på den, stänger av den och gör finjusteringar. Men vad händer om en klient använder vår programvara på ett sätt som vi inte förväntade oss? Eller har den fel som vi inte tänkt på?

För att säkerställa att dokumentationen är så komplett som möjligt rekommenderar vi att du analyserar supportförfrågningar, frågor på tematiska forum och frågor i sökmotorer. De mest populära ämnena kommer att överföras till tekniska skribenter så att de kan komplettera befintliga artiklar eller skriva nya.

Dokumentationen förbättras inte

Det är svårt att göra det perfekt direkt, det kommer fortfarande att finnas misstag. Du kan hoppas på feedback från kunder, men det är osannolikt att de kommer att rapportera varje stavfel, felaktighet, obegriplig eller ogrundad artikel. Förutom kunder läser anställda dokumentationen, vilket innebär att de ser samma fel. Detta kan användas! Du behöver bara skapa förutsättningar där det blir lätt att rapportera ett problem.

Vi har en grupp på den interna portalen där medarbetare lämnar kommentarer, förslag och idéer om dokumentation. Behöver supporten en artikel, men den finns inte? Har testaren märkt felaktigheten? Har partnern klagat till utvecklingsansvariga på fel? Alla i denna grupp! Tekniska skribenter fixar vissa saker direkt, överför vissa saker till YouTrack och ger andra lite tid att tänka på. För att förhindra att ämnet dör ner påminner vi då och då om gruppens existens och vikten av feedback.

Problem 3. Det tar lång tid att hitta rätt artikel.

En artikel som inte kan hittas är inte bättre än en artikel som inte kan hittas. Mottot för bra dokumentation bör vara "Lätt att söka, lätt att hitta." Hur uppnår man detta?

Organisera strukturen och bestäm principen för val av ämnen. Strukturen bör vara så transparent som möjligt så att läsaren inte tänker: "Var kan jag hitta den här artikeln?" För att sammanfatta finns det två tillvägagångssätt: från gränssnittet och från uppgifterna.

1. Från gränssnittet. Innehållet duplicerar panelsektionerna. Detta var fallet i den gamla ISPsystem-dokumentationen.
2. Från uppgifter. Titlarna på artiklar och avsnitt speglar användarnas uppgifter; Titlar innehåller nästan alltid verb och svar på "hur man"-frågan. Nu går vi över till detta format.

Oavsett vilket tillvägagångssätt du väljer, se till att ämnet är relevant för vad användarna letar efter och täcks på ett sätt som specifikt tar upp användarens fråga.

Skapa en centraliserad sökning. I en idealisk värld bör sökning fungera även när du stavar fel eller gör ett misstag med språket. Vår sökning i Confluence hittills kan inte glädja oss med detta. Om du har många produkter och dokumentationen är generell, skräddarsy sökningen till sidan som användaren är på. I vårt fall fungerar sökningen på huvudsidan för alla produkter, och om du redan är i en specifik sektion, då bara för artiklarna i den.

Lägg till innehåll och ströbröd. Det är bra när varje sida har en meny och brödsmulor - användarens väg till den aktuella sidan med möjligheten att återgå till vilken nivå som helst. I den gamla ISPsystem-dokumentationen var du tvungen att avsluta artikeln för att komma till innehållet. Det var obekvämt, så vi fixade det i den nya.

Placera länkar i produkten. Om folk kommer för att stödja om och om igen med samma fråga, är det vettigt att lägga till en ledtråd med dess lösning till gränssnittet. Om du har data eller insikt om när en användare upplever ett problem kan du även meddela dem med en e-postlista. Visa dem omtanke och ta bort bördan från stödet.

Till höger i popup-fönstret finns en länk till en artikel om att ställa in DNSSEC i domänhanteringsdelen av ISPmanager

Sätt upp korsreferenser i dokumentationen. Artiklar som är relaterade till varandra ska vara "länkade". Om artiklarna är sekventiella, se till att lägga till framåt- och bakåtpilar i slutet av varje text.

Troligtvis kommer en person först att leta efter ett svar på sin fråga, inte till dig, utan till en sökmotor. Det är synd om det inte finns länkar till dokumentationen där av tekniska skäl. Så ta hand om sökmotoroptimering.

Problem 4. Föråldrad layout stör uppfattningen

Förutom dåliga texter kan dokumentation bli förstörd av design. Människor är vana vid att läsa välskrivet material. Bloggar, sociala nätverk, media - allt innehåll presenteras inte bara vackert, utan också lätt att läsa och tilltalande för ögat. Därför kan du enkelt förstå smärtan hos en person som ser text som i skärmdumpen nedan.

Det finns så många skärmdumpar och höjdpunkter i den här artikeln att de inte hjälper, utan bara stör uppfattningen (bilden är klickbar)

Du bör inte göra en longread från dokumentationen med en massa effekter, men du måste ta hänsyn till de grundläggande reglerna.

Layout. Bestäm brödtextens bredd, teckensnitt, storlek, rubriker och utfyllnad. Anställ en designer och för att acceptera arbetet eller göra det själv, läs Artyom Gorbunovs bok "Typografi och layout." Det visar bara en vy av layouten, men det är helt tillräckligt.

Tilldelningar. Bestäm vad som kräver betoning i texten. Vanligtvis är detta en sökväg i gränssnittet, knappar, kodinlägg, konfigurationsfiler, "Observera"-block. Bestäm vad tilldelningen av dessa element kommer att vara och registrera dem i regelverket. Tänk på att ju mindre flytningar desto bättre. När det är många är texten bullrig. Även citattecken skapar brus om de används för ofta.

Skärmdumpar. Kom överens med teamet i vilka fall skärmdumpar behövs. Det finns definitivt ingen anledning att illustrera varje steg. Ett stort antal skärmdumpar, inkl. separata knappar, stör uppfattningen, förstör layouten. Bestäm storleken, samt formatet för höjdpunkter och signaturer på skärmdumpar, och registrera dem i bestämmelserna. Tänk på att illustrationer alltid ska stämma överens med det som står och vara relevanta. Återigen, om produkten uppdateras regelbundet blir det svårt att hålla reda på alla.

Textlängd. Undvik för långa artiklar. Dela upp dem i delar, och om detta inte är möjligt, lägg till innehåll med ankarlänkar i början av artikeln. Ett enkelt sätt att göra en artikel visuellt kortare är att dölja tekniska detaljer som behövs av en smal krets av läsare under en spoiler.

format. Kombinera flera format i dina artiklar: text, video och bilder. Detta kommer att förbättra uppfattningen.

Försök inte dölja problem med vacker layout. Ärligt talat hoppades vi själva att "omslaget" skulle rädda den föråldrade dokumentationen - det fungerade inte. Texterna innehöll så mycket visuellt brus och onödiga detaljer att regelverket och den nya designen var maktlösa.

Mycket av ovanstående kommer att bestämmas av plattformen du använder för dokumentation. Till exempel har vi Confluence. Jag var tvungen att pyssla med honom också. Om du är intresserad, läs historien om vår webbutvecklare: Sammanflöde för en offentlig kunskapsbas: ändra designen och ställa in separation efter språk.

Var ska man börja förbättra sig och hur man överlever

Om din dokumentation är lika omfattande som ISPsystems och du inte vet var du ska börja, börja med de största problemen. Klienter förstår inte dokumentet – förbättra texterna, stifta föreskrifter, utbilda skribenter. Dokumentation är inaktuell - ta hand om interna processer. Börja med de mest populära artiklarna om de mest populära produkterna: fråga support, titta på webbplatsanalyser och sökfrågor i sökmotorer.

Låt oss säga direkt - det blir inte lätt. Och det är osannolikt att det fungerar snabbt heller. Såvida du inte bara har börjat och gör det rätta direkt. En sak vi med säkerhet vet är att det kommer att bli bättre med tiden. Men processen kommer aldrig att ta slut :-).

Källa: will.com