Documentatie voor software is gewoon een verzameling artikelen. Maar zelfs die kunnen frustrerend zijn. Eerst zoek je lang naar de juiste instructie. Dan probeer je de moeilijk te begrijpen tekst te doorgronden. Je doet wat er geschreven staat, maar het probleem blijft bestaan. Je zoekt een ander artikel, raakt zenuwachtig... Na een uur geef je alles op en ga je weg. Zo werkt slechte documentatie. Wat maakt het zo slecht en hoe kan dit verbeterd worden - lees verder.
Onze oude documentatie had veel tekortkomingen. Al bijna een jaar herzien we deze, zodat het bovengenoemde scenario onze klanten niet raakt. Kijk eens, en .
Probleem 1. Onduidelijke, slecht geschreven artikelen
Als je de documentatie niet kunt begrijpen, wat heeft ze dan voor zin? Maar niemand schrijft opzettelijk onduidelijke artikelen. Ze ontstaan wanneer de auteur niet nadenkt over het publiek en het doel, onnodige details toevoegt en de tekst niet controleert op fouten.
- Publiek. Voor het schrijven van een artikel moet je nadenken over het niveau van de lezers. Het is logisch dat in een artikel voor beginners de basisstappen niet mogen ontbreken en technische termen niet zonder uitleg kunnen worden gelaten, terwijl in een artikel over een zeldzame functie alleen voor professionals de betekenis van het woord PHP niet te diepgaand behandeld hoeft te worden.
- Doel. Nog een ding waar je beter van tevoren over kunt nadenken. De auteur moet een duidelijke doelstelling formuleren, de nuttige actie van het artikel bepalen en besluiten wat de lezer zal doen na het lezen ervan. Als je dat niet doet, krijg je een beschrijving om het beschrijven.
- Onnodige informatie en fouten. Te veel overbodige informatie en bureaucratisch taalgebruik, fouten en typfouten hinderen de leesbaarheid. Zelfs als de lezer geen grammaticanaazist is, kan slordigheid in de tekst hem afschrikken.
Neem de bovenstaande tips in acht, en de artikelen zullen gegarandeerd begrijpelijker worden. Om het nog beter te maken, neem onze .
Probleem 2. Artikelen beantwoorden niet alle vragen
Het is slecht wanneer de documentatie de ontwikkeling niet bijhoudt, niet op echte vragen antwoord geeft en fouten gedurende jaren niet worden gecorrigeerd. Dit zijn problemen die meer te maken hebben met de auteur dan met de organisatie van de processen binnen het bedrijf.
Documentatie houdt de ontwikkeling niet bij
Deze functie is al uitgebracht, de marketingafdeling is van plan het te belichten, en dan blijkt dat er nog steeds geen nieuw artikel of vertaling in de documentatie staat. Hierdoor hebben we zelfs de release moeten uitstellen. Je kunt iedereen blijven vragen om taken op tijd aan de technische schrijvers door te geven, maar dat zal niet werken. Als het proces niet wordt geautomatiseerd, zal de situatie zich blijven herhalen.
We hebben veranderingen aangebracht in YouTrack. De taak om een artikel over de nieuwe functie te schrijven, komt meteen bij de technische schrijver terecht wanneer de mogelijkheid wordt getest. Dan hoort de marketingafdeling er ook van, zodat ze zich kunnen voorbereiden op de promotie. Meldingen komen ook binnen via de bedrijfsberichtenapp Mattermost, waardoor het bijna onmogelijk is om het nieuws van de ontwikkelaars te missen.
De documentatie weerspiegelt niet de wensen van de gebruikers.
We zijn gewend om zo te werken: de functie is uitgekomen, en we delen het. We beschrijven hoe je het aan en uit zet en hoe je fijne instellingen maakt. Maar wat als de klant onze software gebruikt op een manier die wij niet hadden voorzien? Of als er fouten optreden waar we niet aan gedacht hebben?
Om de documentatie zo volledig mogelijk te maken, adviseren we om aanvragen naar de ondersteuning, vragen op thematische forums en zoekopdrachten in zoekmachines te analyseren. De meest populaire onderwerpen doorspelen aan de technische schrijvers, zodat zij de bestaande artikelen kunnen aanvullen of nieuwe kunnen schrijven.
De documentatie wordt niet verbeterd.
Het is moeilijk om het meteen perfect te doen; er zullen altijd fouten zijn. Je kunt hopen op feedback van klanten, maar waarschijnlijk zullen ze niet elke typefout, onjuistheid, onduidelijke of niet-gevonden artikel melden. Naast klanten lezen ook medewerkers de documentatie, en zij zien dezelfde fouten. Dit kun je benutten! Je moet alleen de voorwaarden creëren waarin het gemakkelijk is om een probleem te melden.
We hebben een groep op het interne portaal waar medewerkers opmerkingen, voorstellen en ideeën over de documentatie achterlaten. Heeft de ondersteuning een artikel nodig dat er niet is? Heeft een tester een onnauwkeurigheid opgemerkt? Heeft een partner geklaagd bij de accountmanagers over fouten? Alles gaat naar deze groep! Technische schrijvers corrigeren sommige dingen meteen, zetten andere in YouTrack of nemen ze mee om erover na te denken. Om ervoor te zorgen dat het onderwerp niet verwatert, herinneren we af en toe aan het bestaan van de groep en het belang van feedback.
Probleem 3. Het gewenste artikel is moeilijk te vinden.
Een artikel dat niet te vinden is, is niet beter dan een artikel dat er niet is. De slogan van goede documentatie moet zijn: "Gemakkelijk te zoeken, gemakkelijk te vinden". Hoe bereik je dit?
De structuur ordenen en het selectieprincipe van onderwerpen bepalen. De structuur moet zo transparant mogelijk zijn, zodat de lezer zich niet afvraagt: "Waar kan ik dit artikel vinden?" In het algemeen zijn er twee benaderingen: van de interface en van taken.
- Van de interface. De inhoud herhaalt de secties van het paneel. Dit was het geval in de oude documentatie van ISPsystem.
- Van taken. De titels van artikelen en secties weerspiegelen de behoeften van gebruikers; in de titels staan bijna altijd werkwoorden en antwoorden op de vraag "hoe doe je dat". We stappen nu over naar dit formaat.
Welke benadering je ook kiest, zorg ervoor dat het onderwerp aansluit bij de vragen van de gebruikers en op een manier is behandeld dat de gebruiker zijn vraag zeker kan oplossen.
Een gecentraliseerde zoekfunctie opzetten. In een ideale wereld zou de zoekfunctie moeten werken, zelfs als je een typfout maakt of de verkeerde taal gebruikt. Onze zoekfunctie in Confluence kan daar momenteel niet mee uitpakken. Als je veel producten hebt en de documentatie algemeen is, pas dan de zoekfunctie aan aan de pagina waar de gebruiker zich bevindt. In ons geval werkt de zoekfunctie op de startpagina voor alle producten, en als je al in een specifieke sectie bent, dan alleen voor de artikelen daarin.
Inhoud en 'broodkruimels' toevoegen. Het is fijn als elke pagina een menu en broodkruimels heeft — het pad dat de gebruiker naar de huidige pagina heeft afgelegd met de mogelijkheid om naar elk niveau terug te keren. In de oude documentatie van ISPsystem moest je de artikel verlaten om naar de inhoud te gaan. Dit was onhandig, dus we hebben dit in de nieuwe versie verbeterd.
Links in het product plaatsen. Als mensen keer op keer met dezelfde vraag bij de ondersteuning komen, is het verstandig om een hint met de oplossing in de interface op te nemen. Als je gegevens of inzicht hebt over het moment waarop de gebruiker met een probleem wordt geconfronteerd, kun je hem ook via een nieuwsbrief inlichten. Zo toon je zorg en verlicht je de druk op de ondersteuning.
Aan de rechterkant in de pop-up een link naar het artikel over het instellen van DNSSEC in de sectie domeinbeheer van ISPmanager
Kruislinks binnen de documentatie instellenArtikelen die met elkaar verbonden zijn, moeten "gelinkt" worden. Als artikelen een reeks vormen, voeg dan aan het einde van elke tekst pijlen naar voren en achteren toe.
Waarschijnlijk zal iemand eerst zijn antwoord niet bij jou, maar in de zoekmachine zoeken. Het is jammer als er om technische redenen geen links naar de documentatie zijn. Zorg dus voor zoekmachineoptimalisatie.
Probleem 4. Verouderde opmaak hindert de waarneming
Naast slechte teksten kan ook het ontwerp de documentatie verpesten. Mensen zijn gewend goed opgemaakte materialen te lezen. Blogs, sociale media, media — alle inhoud wordt niet alleen mooi, maar ook prettig leesbaar gepresenteerd. Daarom is het gemakkelijk om de pijn te begrijpen van iemand die tekst ziet zoals op de onderstaande screenshot.
In dit artikel zijn er zoveel screenshots en markeringen dat ze niet helpen, maar de waarneming alleen maar verstoren (afbeelding is klikbaar)
Het is niet nodig om van de documentatie een lange lezing met veel effecten te maken, maar de basisregels moeten wel in acht worden genomen.
Opmaak. Bepaal de breedte van de hoofdtekst, het lettertype, de grootte, de koppen en de marges. Schakel een ontwerper in, en om het werk te beoordelen of zelf aan de slag te gaan, lees het boek van Artem Gorbunov "Typografie en opmaak". Dit is slechts één kijk op opmaak, maar het is meer dan genoeg.
Markeringen. Bepaal welke delen van de tekst aandacht vereisen. Dit zijn meestal paden in de interface, knoppen, code-invoegen, configuratiebestanden, blokken "Let op". Stel vast hoe deze elementen gemarkeerd worden en leg dit vast in de richtlijnen. Houd er rekening mee dat hoe minder markeringen, hoe beter. Als er veel zijn, "ruist" de tekst. Zelfs aanhalingstekens creëren ruis als ze te vaak worden gebruikt.
Screenshots. Maak afspraken met het team in welke gevallen screenshots nodig zijn. Het is niet nodig om elke stap te illustreren. Een grote hoeveelheid screenshots, inclusief afzonderlijke knopjes, hindert de waarneming en verpest de opmaak. Bepaal de grootte en het formaat van markeringen en bijschriften op de screenshots, en leg dit vast in de richtlijnen. Vergeet niet dat illustraties altijd relevant moeten zijn voor de tekst en actueel moeten zijn. Nogmaals, als het product regelmatig wordt bijgewerkt, is het moeilijk om alles bij te houden.
Lengte van de tekst. Vermijd te lange artikelen. Verdeel ze in secties en als dat niet mogelijk is, voeg dan een inhoudsopgave met ankertags aan het begin toe. Een eenvoudige manier om een artikel visueel korter te maken, is door technische details, die alleen voor een klein publiek relevant zijn, onder een spoiler te verbergen.
Formaten. Combineer verschillende formaten in artikelen: tekst, video en afbeeldingen. Dit verbetert de leeservaring.
Probeer problemen niet te verbergen achter een mooie lay-out. Eerlijk gezegd hoopten we ook dat de 'omslag' verouderde documentatie zou redden — dat gebeurde niet. De teksten waren vol visuele rommel en onnodige details, waardoor de regels en het nieuwe ontwerp geen effect hadden.
Veel van het bovenstaande zal afhangen van het platform dat je gebruikt voor documentatie. Voor ons is dat bijvoorbeeld Confluence. Daar hebben we ook een tijdje mee geknutseld. Als je geïnteresseerd bent, lees dan het verhaal van onze webdeveloper: .
Waar te beginnen met verbeteringen en hoe te overleven
Als je documentatie zo onmetelijk is als die van ISPsystem, en je weet niet waar te beginnen, begin dan met de meest urgente problemen. Klanten begrijpen de documentatie niet — verbeter de teksten, maak richtlijnen, train schrijvers. Documentatie is verouderd — pak de interne processen aan. Begin met de populairste artikelen over de meest gevraagde producten: vraag de ondersteuning, bekijk de site-analyse en zoekopdrachten in zoekmachines.
Om eerlijk te zijn — het wordt niet gemakkelijk. En snel ook waarschijnlijk niet. Tenzij je net begint en het meteen goed doet. Eén ding weten we zeker — het zal met de tijd beter worden. Maar het proces eindigt nooit :-).
Bron: habr.com
