Softwaredokumentation er blot et sæt artikler. Men selv de kan drive dig til vanvid. For det første bruger du lang tid på at lede efter de nødvendige instruktioner. Så forstår du den dunkle tekst. Du gør som skrevet, men problemet er ikke løst. Hvis du leder efter en anden artikel, bliver du nervøs... En time senere giver du op på alt og går. Sådan fungerer dårlig dokumentation. Hvad gør det sådan og hvordan du fikser det - læs under snittet.
Der var mange mangler i vores gamle dokumentation. Vi har omarbejdet det i næsten et år nu, så det ovenfor beskrevne scenario ikke påvirker vores kunder. Se, и .
Problem 1: Uklare, dårligt skrevne artikler
Hvis dokumentationen er umulig at forstå, hvad er så meningen med den? Men ingen skriver uforståelige artikler med vilje. De sker, når forfatteren ikke tænker på publikum og formål, hælder vand og ikke tjekker teksten for fejl.
- Publikum. Før du skriver en artikel, skal du tænke over læserens forberedelsesniveau. Det er logisk, at du i en artikel for en begynder ikke skal springe over grundlæggende trin og lade tekniske termer stå uden forklaring, men i en artikel om en sjælden funktion, som kun fagfolk har brug for, bør du ikke forklare betydningen af ordet PHP.
- mål. Endnu en ting at tænke over på forhånd. Forfatteren skal sætte et klart mål, bestemme artiklens nyttige effekt og beslutte, hvad læseren vil gøre efter at have læst den. Hvis dette ikke gøres, ender du med beskrivelse for beskrivelsens skyld.
- Vand og insekter. Der er en masse unødvendig information og bureaukrati, fejl og tastefejl forstyrrer opfattelsen. Selvom læseren ikke er grammatiknazist, kan skødesløshed i teksten slå ham af.
Overvej tipsene ovenfor, og artiklerne bliver mere overskuelige – garanteret. For at gøre det endnu bedre, brug vores .
Problem 2. Artikler besvarer ikke alle spørgsmål
Det er dårligt, når dokumentationen ikke følger med udviklingen, ikke svarer på rigtige spørgsmål, og fejl i den ikke bliver rettet i årevis. Det er ikke så meget problemer for forfatteren, men om organiseringen af processer i virksomheden.
Dokumentation følger ikke med udviklingen
Funktionen er allerede udgivet, marketing planlægger at dække den, og så viser det sig, at den nye artikel eller oversættelse stadig ikke er i dokumentationen. Vi var endda nødt til at udsætte udgivelsen på grund af dette. Du kan bede alle om at overdrage opgaver til tekniske skribenter til tiden, så meget du vil, men det virker ikke. Hvis processen ikke er automatiseret, vil situationen gentage sig selv.
Vi har lavet ændringer til YouTrack. Opgaven med at skrive en artikel om en ny funktion påhviler den tekniske skribent i samme øjeblik, hvor funktionen begynder at blive testet. Så lærer marketing om det for at forberede sig til promovering. Notifikationer kommer også til Mattermost corporate messenger, så det er simpelthen umuligt at gå glip af nyheder fra udviklere.
Dokumentation afspejler ikke brugerønsker
Vi er vant til at arbejde sådan her: en funktion kom ud, vi talte om den. Vi beskrev, hvordan du tænder, slukker og laver finjusteringer. Men hvad nu hvis en klient bruger vores software på en måde, vi ikke havde forventet? Eller har den fejl, som vi ikke har tænkt over?
For at sikre, at dokumentationen er så fuldstændig som muligt, anbefaler vi at analysere supportanmodninger, spørgsmål om tematiske fora og forespørgsler i søgemaskiner. De mest populære emner vil blive overført til tekniske skribenter, så de kan supplere eksisterende artikler eller skrive nye.
Dokumentationen bliver ikke forbedret
Det er svært at gøre det perfekt med det samme; der vil stadig være fejl. Du kan håbe på feedback fra kunder, men det er usandsynligt, at de vil rapportere enhver tastefejl, unøjagtighed, uforståelig eller ufunderet artikel. Ud over kunder læser medarbejderne dokumentationen, hvilket betyder, at de ser de samme fejl. Dette kan bruges! Du skal blot skabe betingelser, hvor det bliver nemt at rapportere et problem.
Vi har en gruppe på den interne portal, hvor medarbejdere kommer med kommentarer, forslag og ideer til dokumentation. Har support brug for en artikel, men den findes ikke? Har testeren bemærket unøjagtigheden? Har partneren klaget til udviklingschefer over fejl? Alle i denne gruppe! Tekniske skribenter ordner nogle ting med det samme, overfører nogle ting til YouTrack og giver andre lidt tid til at tænke over. For at forhindre, at emnet dør, minder vi fra tid til anden om gruppens eksistens og vigtigheden af feedback.
Problem 3. Det tager lang tid at finde den rigtige artikel.
En artikel, der ikke kan findes, er ikke bedre end en artikel, der ikke kan findes. Mottoet for god dokumentation bør være "Let at søge, let at finde." Hvordan opnår man dette?
Organiser strukturen og bestem princippet for valg af emner. Strukturen skal være så gennemsigtig som muligt, så læseren ikke tænker: "Hvor kan jeg finde denne artikel?" For at opsummere er der to tilgange: fra grænsefladen og fra opgaverne.
- Fra grænsefladen. Indholdet dublerer panelsektionerne. Dette var tilfældet i den gamle ISPsystem-dokumentation.
- Fra opgaver. Titlerne på artikler og afsnit afspejler brugernes opgaver; Titler indeholder næsten altid verber og svar på "hvordan"-spørgsmålet. Nu går vi over til dette format.
Uanset hvilken tilgang du vælger, skal du sørge for, at emnet er relevant for det, brugerne leder efter, og er dækket på en måde, der specifikt adresserer brugerens spørgsmål.
Opret en centraliseret søgning. I en ideel verden burde søgning fungere, selv når du staver forkert eller laver en fejl med sproget. Vores søgning i Confluence hidtil kan ikke glæde os med dette. Hvis du har mange produkter og dokumentationen er generel, så skræddersy søgningen til den side brugeren er på. I vores tilfælde virker søgningen på hovedsiden for alle produkter, og hvis du allerede er i en specifik sektion, så kun for artiklerne i den.
Tilføj indhold og brødkrummer. Det er godt, når hver side har en menu og brødkrummer - brugerens vej til den aktuelle side med mulighed for at vende tilbage til ethvert niveau. I den gamle ISPsystem-dokumentation skulle du afslutte artiklen for at komme til indholdet. Det var ubelejligt, så vi fiksede det i den nye.
Placer links i produktet. Hvis folk kommer til at støtte igen og igen med det samme spørgsmål, giver det mening at tilføje et hint med dets løsning til grænsefladen. Hvis du har data eller indsigt i, hvornår en bruger oplever et problem, kan du også give dem besked med en mailingliste. Vis dem bekymring og tag byrden af støtten.
Til højre i pop op-vinduet er et link til en artikel om opsætning af DNSSEC i domæneadministrationssektionen i ISPmanager
Opsæt krydsreferencer i dokumentation. Artikler, der er relateret til hinanden, bør "linkes". Hvis artiklerne er sekventielle, skal du sørge for at tilføje frem- og tilbagepile i slutningen af hver tekst.
Mest sandsynligt vil en person først gå på udkig efter et svar på sit spørgsmål, ikke til dig, men til en søgemaskine. Det er en skam, hvis der ikke er links til dokumentationen der af tekniske årsager. Så tag dig af søgemaskineoptimering.
Opgave 4. Forældet layout forstyrrer opfattelsen
Ud over dårlige tekster kan dokumentation være spoleret af design. Folk er vant til at læse velskrevne materialer. Blogs, sociale netværk, medier - alt indhold præsenteres ikke kun smukt, men også let at læse og en fryd for øjet. Derfor kan du nemt forstå smerten ved en person, der ser tekst som på skærmbilledet nedenfor.
Der er så mange skærmbilleder og højdepunkter i denne artikel, at de ikke hjælper, men kun forstyrrer opfattelsen (billedet er klikbart)
Du bør ikke lave en longread fra dokumentationen med en masse effekter, men du skal tage højde for de grundlæggende regler.
Layout. Bestem brødtekstbredde, skrifttype, størrelse, overskrifter og udfyldning. Hyr en designer, og for at acceptere arbejdet eller gøre det selv, læs Artyom Gorbunovs bog "Typography and Layout." Det viser kun én visning af layoutet, men det er ganske tilstrækkeligt.
Tildelinger. Bestem, hvad der skal fremhæves i teksten. Typisk er dette en sti i grænsefladen, knapper, kodeindsættelser, konfigurationsfiler, "Bemærk venligst"-blokke. Bestem, hvad tildelingen af disse elementer vil være, og registrer dem i reglerne. Husk, at jo mindre udflåd, jo bedre. Når der er mange af dem, larmer teksten. Selv anførselstegn skaber støj, hvis de bruges for ofte.
Skærmbilleder. Aftal med teamet i hvilke tilfælde skærmbilleder er nødvendige. Der er absolut ingen grund til at illustrere hvert trin. Et stort antal skærmbilleder, inkl. separate knapper, forstyrrer opfattelsen, ødelægger layoutet. Bestem størrelsen, samt formatet af højdepunkter og signaturer på skærmbilleder, og optag dem i reglerne. Husk at illustrationer altid skal svare til det skrevne og være relevante. Igen, hvis produktet opdateres regelmæssigt, vil det være svært at holde styr på alle.
Tekstlængde. Undgå alt for lange artikler. Del dem op i dele, og hvis dette ikke er muligt, tilføj indhold med ankerlinks til begyndelsen af artiklen. En enkel måde at gøre en artikel visuelt kortere på er at skjule tekniske detaljer, der er nødvendige for en snæver kreds af læsere, under en spoiler.
formater. Kombiner flere formater i dine artikler: tekst, video og billeder. Dette vil forbedre opfattelsen.
Forsøg ikke at dække over problemer med smukt layout. Helt ærligt håbede vi selv, at "indpakningen" ville gemme den forældede dokumentation - det lykkedes ikke. Teksterne indeholdt så meget visuel støj og unødvendige detaljer, at reglerne og det nye design var magtesløse.
Meget af ovenstående vil blive bestemt af den platform, du bruger til dokumentation. For eksempel har vi Confluence. Jeg måtte også pille ved ham. Hvis du er interesseret, så læs historien om vores webudvikler: .
Hvor skal man begynde at forbedre sig, og hvordan man overlever
Hvis din dokumentation er lige så omfattende som ISP-systemets, og du ikke ved, hvor du skal starte, så start med de største problemer. Klienter forstår ikke dokumentet - forbedre teksterne, lav regler, uddanne forfattere. Dokumentation er forældet - tag hånd om interne processer. Start med de mest populære artikler om de mest populære produkter: spørg support, kig på webstedsanalyser og forespørgsler i søgemaskiner.
Lad os sige med det samme - det bliver ikke nemt. Og det er usandsynligt, at det virker hurtigt heller. Medmindre du lige er startet og gør det rigtige med det samme. En ting vi med sikkerhed ved er, at det bliver bedre med tiden. Men processen vil aldrig ende :-).
Kilde: www.habr.com