Dokumentationen til softwaren er blot en samling artikler. Men selv de kan være frustrerende. Først søger du længe efter den rette instruktion. Så kæmper du med en uklar tekst. Du gør som beskrevet, men problemet forbliver uløst. Du leder efter en anden artikel, bliver nervøs… Efter en time giver du op og stopper. Sådan fungerer dårlig dokumentation. Hvad gør den sådan, og hvordan kan man rette op på det – læs videre.
I vores gamle dokumentation var der mange mangler. I næsten et år har vi arbejdet på at forbedre den, så det nævnte scenarie ikke berører vores kunder. Se her, og .
Problem 1. Uklare, dårligt skrevne artikler
Hvis man ikke kan forstå dokumentationen, hvad er meningen så? Ingen skriver uklare artikler med vilje. De opstår, når forfatteren ikke tænker på publikum og formål, fylder teksten med irrelevant indhold og ikke tjekker for fejl.
- Publikum. Før man skriver en artikel, skal man overveje læserens forudsætninger. Det er logisk, at i en artikel til begyndere skal man ikke springe grundlæggende skridt over eller lade tekniske termer uddybe uden forklaring, mens en artikel om en sjælden funktion, der kun er relevant for professionelle, skal uddybe betydningen af ordet PHP.
- Formålet. Endnu en ting, der bør overvejes på forhånd. Forfatteren skal sætte et klart mål, definere den nyttige handling artiklen skal fremkalde, og bestemme, hvad læseren vil gøre efter at have læst den. Hvis dette ikke gøres, ender det som en beskrivelse for beskrivelsens skyld.
- Overflødig information og fejl. For meget irrelevant information og bureaukratiske vendinger, samt stavefejl og trykfejl, hindrer forståelsen. Selv hvis læseren ikke er en grammatikhund, kan uagtsomhed i teksten afskrække vedkommende.
Tag hensyn til ovenstående råd, så bliver artiklerne mere klare – det er garanteret. For at gøre det endnu bedre, tag vores .
Problem 2. Artiklerne besvarer ikke alle spørgsmål
Det er dårligt, når dokumentationen ikke følger med udviklingen, ikke besvarer virkelige spørgsmål, og fejl i den ikke rettes i årevis. Det er ikke kun et problem for forfatteren, men også for organisationen af processerne i virksomheden.
Dokumentationen følger ikke med udviklingen
Funktionen er allerede i release, marketing planlægger at belyse den, og her viser det sig, at der stadig ikke er nogen ny artikel eller oversættelse i dokumentationen. På grund af dette har vi endda været nødt til at udskyde releasen. Man kan bede alle om rettidigt at videregive opgaven til tekniske skribenter, men det vil ikke fungere. Hvis processen ikke automatiseres, vil situationen gentage sig.
Vi har foretaget ændringer i YouTrack. Opgaven til at skrive en artikel om den nye funktion falder til den tekniske skribent i det øjeblik, muligheden begynder at blive testet. På samme tid bliver marketing opmærksom på det for at forberede sig til promoveringen. Notifikationer kommer også i virksomhedens messenger Mattermost, så det er umuligt at gå glip af nyheder fra udviklerne.
Dokumentationen afspejler ikke brugernes forespørgsler
Vi er vant til at arbejde sådan: funktionen er udgivet, vi fortæller om den. Vi beskriver, hvordan man aktiverer, deaktiverer og foretager finindstillinger. Men hvad hvis kunden bruger vores software på en måde, vi ikke havde forudset? Eller hvis de støder på fejl, som vi ikke har tænkt på?
For at dokumentationen skal være så komplet som muligt, anbefaler vi at analysere henvendelser til support, spørgsmål på temafora, forespørgsler i søgerne. De mest populære emner skal videregives til de tekniske skribenter, så de kan supplere de eksisterende artikler eller skrive nye.
Dokumentationen forbedres ikke
Det er svært at gøre det perfekt fra starten, der vil altid være fejl. Man kan håbe på feedback fra kunderne, men det er usandsynligt, at de vil rapportere hver stavefejl, ukorrekthed, utydelig eller ikke-fundet artikel. Udover kunderne læser medarbejderne også dokumentationen, hvilket betyder, at de ser de samme fejl. Dette kan udnyttes! Man skal bare skabe betingelser, hvor det er nemt at rapportere et problem.
Vi har en gruppe på den interne portal, hvor medarbejdere kan give bemærkninger, forslag og idéer til dokumentationen. Har supporten brug for en artikel, men der findes ingen? En tester bemærkede en unøjagtighed? En partner klagede til udviklingscheferne over fejl? Alt i denne gruppe! De tekniske skribenter retter noget straks, noget overfører til YouTrack, noget tager med til overvejelse. For at emnet ikke skal stille, minder vi tid til anden tid om eksistensen af gruppen og vigtigheden af feedback.
Problem 3. Den nødvendige artikel skal der søges længe efter
En artikel, der ikke kan findes, er ikke bedre end en, der ikke eksisterer. Et godt dokumentationsprincip bør være sætningen 'Nem at søge, nem at finde'. Hvordan kan det opnås?
Organisere strukturen og definere princippet for emnevalg. Strukturen skal være så gennemsigtig som muligt, så læseren ikke tænker 'Hvor kan jeg finde denne artikel?'. Hvis vi skal sammenfatte det, er der to tilgange: fra brugergrænsefladen og fra opgaver.
- Fra brugergrænsefladen. Indholdet duplicerer sektionerne i panelet. Sådan var det i den gamle dokumentation fra ISPsystem.
- Fra opgaver. Artikler og sektioners titler afspejler brugernes opgaver; overskrifterne indeholder næsten altid verber og svar på spørgsmålet 'hvordan gør man'. Nu bevæger vi os mod et sådant format.
Uanset hvilken tilgang du vælger, skal du sikre dig, at emnet svarer til brugernes forespørgsler og dækker det på en måde, så brugeren præcist kan få sit spørgsmål besvaret.
Etablere central søgning. I en ideel verden skal søgningen fungere, selv når man laver stavefejl eller laver en sproglig fejl. Vores søgning i Confluence kan endnu ikke tilfredsstille dette. Hvis du har mange produkter, og dokumentationen er generel, tilpas søgningen til den side, hvor brugeren befinder sig. I vores tilfælde fungerer søgningen på forsiden for alle produkter, men hvis du allerede er i en bestemt sektion, sker det kun for artikler i den.
Tilføje indholdsfortegnelse og 'brødkrummer'. Det er godt, når der er en menu og brødkrummer på hver side - brugerens vej til den aktuelle side med mulighed for at gå tilbage til ethvert niveau. I den gamle dokumentation fra ISPsystem skulle man forlade artiklen for at komme til indholdsfortegnelsen. Det var besværligt, så vi har rettet dette i den nye.
Indsætte links i produktet. Hvis folk gang på gang kontakter support med det samme spørgsmål, er det fornuftigt at tilføje en prompt med løsningen i grænsefladen. Hvis du har data eller indsigt i, hvornår brugeren støder på problemet, kan du også underrette ham via et nyhedsbrev. Det viser omsorg og aflaster supporten.
Til højre i pop-op-vinduet er der et link til artiklen om indstilling af DNSSEC i sektionen til domæneadministration i ISPmanager
Opsætning af krydslinks inden for dokumentationenArtikler, der er relateret til hinanden, skal være "linket". Hvis artiklerne udgør en sekvens, skal du sørge for at tilføje pile fremad og tilbage i slutningen af hver tekst.
Sandsynligvis vil personen først søge svar på sit spørgsmål ikke hos dig, men i en søgemaskine. Det er ærgerligt, hvis dokumentationslinks dér ikke er tilgængelige af tekniske årsager. Så sørg for at fokusere på søgemaskineoptimering.
Problem 4. Uddateret layout forstyrrer forståelsen
Ud over dårlige tekster kan dokumentationen også blive ødelagt af designet. Folk er vant til at læse godt strukturerede materialer. Blogs, sociale medier, medier – alt indhold præsenteres ikke bare flot, men også i en læsevenlig og behagelig stil. Derfor er det let at forstå smerten hos en person, der ser tekst som på skærmbilledet nedenfor.
I denne artikel er der så mange skærmbilleder og fremhævelser, at de ikke hjælper, men kun forstyrrer forståelsen (billedet er klikbart)
Det er ikke en god idé at gøre dokumentationen til en longread med masser af effekter, men de grundlæggende regler skal tages i betragtning.
Layout. Bestem bredden på hovedteksten, skrifttype, størrelse, overskrifter og marginer. Involver en designer, eller for at kunne vurdere arbejdet eller klare det selv, læs bogen af Artem Gorbunov "Typografi og layout". Den præsenterer blot én synsvinkel på layout, men det er tilstrækkeligt.
Fremhævelser. Bestem, hvad der kræver fokus i teksten. Normalt er dette stien i grænsefladen, knapper, kodeindsættelser, konfigurationsfiler, sektioner "Vær opmærksom". Angiv, hvordan fremhævelserne af disse elementer skal være, og fastsæt dem i retningslinjerne. Husk, at jo færre fremhævelser, jo bedre. Når der er mange, bliver teksten "støjende". Støj kan endda skabes af citationstegn, hvis de bruges for ofte.
Screenshots. Aftal med teamet, hvornår skærmbilleder er nødvendige. Det er ikke nødvendigt at illustrere hvert trin. Et stort antal skærmbilleder, inklusive individuelle knapper, forstyrrer forståelsen og ødelægger layoutet. Bestem størrelsen samt formatet på fremhævelser og billedtekster på skærmbillederne, og fastsæt dem i retningslinjerne. Husk, at illustrationer altid skal være relevante og matche det skrevne. Igen, hvis produktet opdateres regelmæssigt, kan det være svært at holde styr på hver ændring.
Tekstlængde. Undgå alt for lange artikler. Del dem op i dele, og hvis det ikke er muligt, tilføj en indholdsfortegnelse med ankerlinks i begyndelsen af artiklen. En enkel måde at gøre artiklen visuelt kortere på er at skjule tekniske detaljer, som kun er relevante for en lille gruppe læsere, under en spoiler.
Formater. Kombiner flere formater i artiklerne: tekst, video og billeder. Det vil forbedre forståelsen.
Forsøg ikke at dække over problemer med en flot design. Ærligt talt, vi håbede selv, at 'indpakningen' ville redde forældet dokumentation — det gjorde den ikke. Der var så meget visuel støj og unødvendige detaljer i teksterne, at reglerne og det nye layout var magtesløse.
Meget af det ovenfor beskrevne vil blive bestemt af den platform, du bruger til dokumentationen. For os er det for eksempel Confluence. Det krævede også en del arbejde. Hvis du er interesseret, kan du læse vores webudviklers fortælling: .
Hvor skal man begynde forbedringer, og hvordan overlever man
Hvis din dokumentation er lige så omfattende som ISPsystem's, og du ikke ved, hvor du skal starte, så begynd med de mest alvorlige problemer. Hvis kunderne ikke forstår dokumentationen — fokusér på at forbedre teksterne, lav retningslinjer, og træne forfatterne. Er dokumentationen ikke aktuel — tag fat på interne processer. Start med de mest populære artikler om de mest efterspurgte produkter: spørg supporten, se på webanalysedataene og søgningerne i søgemaskinerne.
Lad os sige det med det samme — det bliver ikke nemt. Og hurtigt vil det næppe ske. Medmindre du lige er startet og gør det rigtigt fra starten. Én ting ved vi helt sikkert — over tid bliver det bedre. Men processen vil aldrig afsluttes :-).
Kilde: habr.com
