Programvaredokumentasjon er bare et sett med artikler. Men selv de kan gjøre deg gal. For det første bruker du lang tid på å lete etter de nødvendige instruksjonene. Da forstår du den obskure teksten. Du gjør som skrevet, men problemet er ikke løst. Du ser etter en annen artikkel, du blir nervøs... En time senere gir du opp alt og drar. Slik fungerer dårlig dokumentasjon. Hva gjør det slik og hvordan du fikser det - les under kuttet.
Det var mange mangler ved vår gamle dokumentasjon. Vi har omarbeidet det i nesten et år nå, slik at scenariet beskrevet ovenfor ikke påvirker kundene våre. Se, и .
Oppgave 1: Uklare, dårlig skrevne artikler
Hvis dokumentasjonen er umulig å forstå, hva er vitsen med den? Men ingen skriver uforståelige artikler med vilje. De skjer når forfatteren ikke tenker på publikum og formål, heller vann og ikke sjekker teksten for feil.
- Forelesningssal. Før du skriver en artikkel, må du tenke på leserens forberedelsesnivå. Det er logisk at i en artikkel for en nybegynner bør du ikke hoppe over de grunnleggende trinnene og la tekniske termer stå uten forklaring, men i en artikkel om en sjelden funksjon som bare fagfolk trenger, bør du forklare betydningen av ordet PHP.
- target. En ting til å tenke på på forhånd. Forfatteren må sette seg et klart mål, bestemme den nyttige effekten av artikkelen, og bestemme hva leseren vil gjøre etter å ha lest den. Hvis dette ikke gjøres, ender du opp med beskrivelse for beskrivelsens skyld.
- Vann og insekter. Det er mye unødvendig informasjon og byråkrati, feil og skrivefeil forstyrrer oppfatningen. Selv om leseren ikke er grammatikknazist, kan slurv i teksten slå ham av.
Vurder tipsene ovenfor, så blir artiklene klarere – garantert. For å gjøre det enda bedre, bruk vår .
Oppgave 2. Artikler svarer ikke på alle spørsmål
Det er dårlig når dokumentasjonen ikke følger med utviklingen, ikke svarer på reelle spørsmål, og feil i den ikke blir rettet på flere år. Dette er ikke så mye problemer for forfatteren, men organiseringen av prosesser i bedriften.
Dokumentasjon holder ikke tritt med utviklingen
Funksjonen er allerede utgitt, markedsføringen planlegger å dekke den, og så viser det seg at den nye artikkelen eller oversettelsen fortsatt ikke er i dokumentasjonen. Vi måtte til og med utsette utgivelsen på grunn av dette. Du kan be alle om å overlate oppgaver til tekniske skribenter i tide så mye du vil, men det vil ikke fungere. Hvis prosessen ikke er automatisert, vil situasjonen gjenta seg.
Vi har gjort endringer i YouTrack. Oppgaven med å skrive en artikkel om en ny funksjon faller på den tekniske skribenten i samme øyeblikk som funksjonen begynner å bli testet. Deretter lærer markedsføring om det for å forberede seg på promotering. Varsler kommer også til Mattermost bedriftsmessenger, så det er rett og slett umulig å gå glipp av nyheter fra utviklere.
Dokumentasjon gjenspeiler ikke brukerforespørsler
Vi er vant til å jobbe slik: en funksjon kom ut, vi snakket om den. Vi beskrev hvordan du slår den på, slår den av og gjør finjusteringer. Men hva om en klient bruker programvaren vår på en måte vi ikke forventet? Eller har den feil som vi ikke har tenkt på?
For å sikre at dokumentasjonen er så fullstendig som mulig, anbefaler vi å analysere støtteforespørsler, spørsmål på tematiske fora og spørringer i søkemotorer. De mest populære emnene vil bli overført til tekniske skribenter slik at de kan supplere eksisterende artikler eller skrive nye.
Dokumentasjonen blir ikke forbedret
Det er vanskelig å gjøre det perfekt med en gang; det vil fortsatt være feil. Du kan håpe på tilbakemeldinger fra kunder, men det er usannsynlig at de vil rapportere hver skrivefeil, unøyaktighet, uforståelig eller ufundert artikkel. I tillegg til klienter leser ansatte dokumentasjonen, noe som betyr at de ser de samme feilene. Denne kan brukes! Du trenger bare å skape forhold der det blir enkelt å rapportere et problem.
Vi har en gruppe på internportalen der ansatte legger igjen kommentarer, forslag og ideer om dokumentasjon. Trenger støtte en artikkel, men den eksisterer ikke? La testeren merke til unøyaktigheten? Har partneren klaget til utviklingsledere på feil? Alle i denne gruppen! Tekniske skribenter fikser noen ting med en gang, overfører noen ting til YouTrack og gir andre litt tid til å tenke på. For å forhindre at temaet dør ut, minner vi fra tid til annen om gruppens eksistens og viktigheten av tilbakemeldinger.
Oppgave 3. Det tar lang tid å finne riktig artikkel.
En artikkel som ikke kan bli funnet er ikke bedre enn en artikkel som ikke kan bli funnet. Mottoet for god dokumentasjon bør være "Lett å søke, lett å finne." Hvordan oppnå dette?
Organiser strukturen og bestem prinsippet for valg av emner. Strukturen bør være så gjennomsiktig som mulig, slik at leseren ikke tenker: "Hvor kan jeg finne denne artikkelen?" For å oppsummere er det to tilnærminger: fra grensesnittet og fra oppgavene.
- Fra grensesnittet. Innholdet dupliserer paneldelene. Dette var tilfellet i den gamle ISPsystem-dokumentasjonen.
- Fra oppgaver. Titlene på artikler og seksjoner gjenspeiler oppgavene til brukerne; Titler inneholder nesten alltid verb og svar på "hvordan"-spørsmålet. Nå går vi over til dette formatet.
Uansett hvilken tilnærming du velger, sørg for at emnet er relevant for det brukerne ser etter og dekkes på en måte som spesifikt tar for seg brukerens spørsmål.
Sett opp et sentralisert søk. I en ideell verden bør søk fungere selv når du staver feil eller gjør en feil med språket. Vårt søk i Confluence så langt kan ikke glede oss med dette. Hvis du har mange produkter og dokumentasjonen er generell, skreddersy søket til siden brukeren er på. I vårt tilfelle fungerer søket på hovedsiden for alle produkter, og hvis du allerede er i en bestemt seksjon, så bare for artiklene i den.
Legg til innhold og brødsmuler. Det er bra når hver side har en meny og brødsmuler - brukerens bane til gjeldende side med muligheten til å gå tilbake til hvilket som helst nivå. I den gamle ISPsystem-dokumentasjonen måtte du avslutte artikkelen for å komme til innholdet. Det var upraktisk, så vi fikset det i den nye.
Plasser lenker i produktet. Hvis folk kommer for å støtte igjen og igjen med det samme spørsmålet, er det fornuftig å legge til et hint med løsningen på grensesnittet. Hvis du har data eller innsikt i når en bruker opplever et problem, kan du også varsle vedkommende med en e-postliste. Vis dem bekymring og ta byrden av støtten.
Til høyre i popup-vinduet er en lenke til en artikkel om oppsett av DNSSEC i domeneadministrasjonsdelen av ISPmanager
Sett opp kryssreferanser i dokumentasjon. Artikler som er relatert til hverandre bør være "lenket". Hvis artiklene er sekvensielle, sørg for å legge til forover- og bakoverpiler på slutten av hver tekst.
Mest sannsynlig vil en person først gå på jakt etter et svar på spørsmålet sitt, ikke til deg, men til en søkemotor. Det er synd om det ikke er lenker til dokumentasjonen der av tekniske årsaker. Så ta vare på søkemotoroptimalisering.
Oppgave 4. Utdatert layout forstyrrer persepsjonen
I tillegg til dårlige tekster, kan dokumentasjon bli ødelagt av design. Folk er vant til å lese godt skrevet materiale. Blogger, sosiale nettverk, media - alt innhold presenteres ikke bare vakkert, men også lett å lese og fryd for øyet. Derfor kan du enkelt forstå smerten til en person som ser tekst som i skjermbildet nedenfor.
Det er så mange skjermbilder og høydepunkter i denne artikkelen at de ikke hjelper, men bare forstyrrer persepsjonen (bildet er klikkbart)
Du bør ikke lage en longread fra dokumentasjonen med en haug med effekter, men du må ta hensyn til de grunnleggende reglene.
Oppsett. Bestem brødtekstbredde, skrifttype, størrelse, overskrifter og utfylling. Ansett en designer, og for å godta arbeidet eller gjøre det selv, les Artyom Gorbunovs bok "Typography and Layout." Den viser bare én visning av oppsettet, men det er ganske tilstrekkelig.
Tildelinger. Bestem hva som krever vektlegging i teksten. Vanligvis er dette en bane i grensesnittet, knapper, kodeinnlegg, konfigurasjonsfiler, "Vennligst merk"-blokker. Bestem hva tildelingen av disse elementene skal være og noter dem i forskriften. Husk at jo mindre utflod, jo bedre. Når det er mange av dem, er teksten støyende. Selv anførselstegn skaper støy hvis de brukes for ofte.
Skjermbilder. Avtal med teamet i hvilke tilfeller skjermbilder er nødvendig. Det er definitivt ikke nødvendig å illustrere hvert trinn. Et stort antall skjermbilder, inkl. separate knapper, forstyrrer oppfatningen, ødelegger oppsettet. Bestem størrelsen, samt formatet på høydepunkter og signaturer på skjermbilder, og registrer dem i regelverket. Husk at illustrasjoner alltid skal samsvare med det som er skrevet og være relevante. Igjen, hvis produktet oppdateres jevnlig, vil det være vanskelig å holde styr på alle.
Tekstlengde. Unngå for lange artikler. Del dem i deler, og hvis dette ikke er mulig, legg til innhold med ankerlenker til begynnelsen av artikkelen. En enkel måte å gjøre en artikkel visuelt kortere på er å skjule tekniske detaljer som trengs av en smal krets av lesere under en spoiler.
Форматы. Kombiner flere formater i artiklene dine: tekst, video og bilder. Dette vil forbedre oppfatningen.
Ikke prøv å dekke over problemer med vakker layout. Ærlig talt, vi håpet selv at "innpakningen" ville redde den utdaterte dokumentasjonen - det fungerte ikke. Tekstene inneholdt så mye visuell støy og unødvendige detaljer at regelverket og ny design sto maktesløse.
Mye av det ovennevnte vil bli bestemt av plattformen du bruker for dokumentasjon. For eksempel har vi Confluence. Jeg måtte tukle med ham også. Hvis du er interessert, les historien til vår nettutvikler: .
Hvor kan man begynne å forbedre seg og hvordan man kan overleve
Hvis dokumentasjonen din er like omfattende som ISP-systemets og du ikke vet hvor du skal begynne, start med de største problemene. Klienter forstår ikke dokumentet - forbedre tekstene, lage forskrifter, lære opp forfattere. Dokumentasjon er utdatert - ta vare på interne prosesser. Begynn med de mest populære artiklene om de mest populære produktene: spør support, se på nettstedsanalyse og spørringer i søkemotorer.
La oss si med en gang - det blir ikke lett. Og det er usannsynlig at det fungerer raskt heller. Med mindre du akkurat har begynt og gjør det rette med en gang. En ting vi vet med sikkerhet er at det vil bli bedre over tid. Men prosessen vil aldri ta slutt :-).
Kilde: www.habr.com