Softwaredocumentatie is slechts een reeks artikelen. Maar zelfs zij kunnen je gek maken. Ten eerste ben je lang bezig met het zoeken naar de benodigde instructies. Dan begrijp je de obscure tekst. Je doet wat geschreven staat, maar het probleem is niet opgelost. Je zoekt een ander artikel, je wordt zenuwachtig... Een uur later geef je alles op en vertrek je. Dit is hoe slechte documentatie werkt. Wat maakt het zo en hoe je het kunt repareren - lees onder de snit.
Er waren veel tekortkomingen in onze oude documentatie. We zijn er nu bijna een jaar mee bezig, zodat het hierboven beschreven scenario geen gevolgen heeft voor onze klanten. Kijk, и .
Probleem 1: Onduidelijke, slecht geschreven artikelen
Als de documentatie onmogelijk te begrijpen is, wat is dan het nut ervan? Maar niemand schrijft met opzet onbegrijpelijke artikelen. Ze gebeuren wanneer de auteur niet aan het publiek en het doel denkt, water giet en de tekst niet op fouten controleert.
- toehoorders. Voordat u een artikel schrijft, moet u nadenken over het voorbereidingsniveau van de lezer. Het is logisch dat je in een artikel voor een beginner de basisstappen niet mag overslaan en technische termen zonder uitleg moet laten, maar dat je in een artikel over een zeldzame functie die alleen professionals nodig hebben, de betekenis van het woord PHP moet uitleggen.
- doelwit. Nog iets om vooraf over na te denken. De auteur moet een duidelijk doel stellen, het nuttige effect van het artikel bepalen en beslissen wat de lezer gaat doen na het lezen ervan. Als dit niet wordt gedaan, krijg je een beschrijving ter wille van de beschrijving.
- Water en insecten. Er is veel onnodige informatie en bureaucratie, fouten en typefouten verstoren de perceptie. Zelfs als de lezer geen grammatica-nazi is, kan onzorgvuldigheid in de tekst hem afschrikken.
Houd rekening met de bovenstaande tips en de artikelen worden gegarandeerd duidelijker. Om het nog beter te maken, gebruik onze .
Probleem 2. Artikelen beantwoorden niet alle vragen
Het is slecht als de documentatie de ontwikkeling niet bijhoudt, echte vragen niet beantwoordt en fouten daarin jarenlang niet worden gecorrigeerd. Dit zijn problemen niet zozeer van de auteur, maar van de organisatie van processen binnen het bedrijf.
Documentatie houdt geen gelijke tred met de ontwikkeling
De functie is al uitgebracht, marketingplannen om dit te dekken, en dan blijkt dat het nieuwe artikel of de vertaling nog steeds niet in de documentatie staat. Hierdoor hebben we de release zelfs moeten uitstellen. Je kunt iedereen vragen om taken op tijd aan technisch schrijvers over te dragen, zoveel als je wilt, maar dat werkt niet. Als het proces niet wordt geautomatiseerd, herhaalt de situatie zich.
We hebben wijzigingen aangebracht in YouTrack. De taak van het schrijven van een artikel over een nieuwe functie ligt bij de technisch schrijver op hetzelfde moment waarop het testen van de functie begint. Vervolgens leert marketing ervan om zich voor te bereiden op promotie. Meldingen komen ook naar de zakelijke messenger van Mattermost, dus het is simpelweg onmogelijk om nieuws van ontwikkelaars te missen.
Documentatie weerspiegelt geen gebruikersverzoeken
We zijn gewend om zo te werken: er kwam een functie uit, we hebben erover gesproken. We hebben beschreven hoe u het in- en uitschakelt en fijne aanpassingen maakt. Maar wat als een klant onze software gebruikt op een manier die wij niet hadden verwacht? Of staan er fouten in waar we niet aan hebben gedacht?
Om ervoor te zorgen dat de documentatie zo volledig mogelijk is, raden wij aan ondersteuningsverzoeken, vragen op thematische forums en zoekopdrachten in zoekmachines te analyseren. De meest populaire onderwerpen worden overgedragen aan technisch schrijvers, zodat zij bestaande artikelen kunnen aanvullen of nieuwe kunnen schrijven.
De documentatie wordt niet verbeterd
Het is moeilijk om het meteen perfect te doen; er zullen nog steeds fouten zijn. Je kunt hopen op feedback van klanten, maar het is onwaarschijnlijk dat zij elke typfout, onjuistheid, onbegrijpelijk of ongevonden artikel zullen melden. Naast klanten lezen ook medewerkers de documentatie, waardoor zij dezelfde fouten zien. Dit kan gebruikt worden! U hoeft alleen maar omstandigheden te creëren waarin het gemakkelijk is om een probleem te melden.
We hebben een groep op het interne portaal waar medewerkers opmerkingen, suggesties en ideeën over documentatie achterlaten. Heeft ondersteuning een artikel nodig, maar bestaat het niet? Heeft de tester de onnauwkeurigheid opgemerkt? Heeft de partner bij ontwikkelingsmanagers geklaagd over fouten? Allemaal in deze groep! Technische schrijvers repareren sommige dingen meteen, zetten sommige dingen over naar YouTrack en geven anderen wat tijd om over na te denken. Om te voorkomen dat het onderwerp uitsterft, herinneren we je van tijd tot tijd aan het bestaan van de groep en het belang van feedback.
Probleem 3. Het duurt lang om het juiste artikel te vinden.
Een artikel dat niet gevonden kan worden is niet beter dan een artikel dat niet gevonden kan worden. Het motto van goede documentatie zou moeten zijn: “Gemakkelijk te zoeken, gemakkelijk te vinden.” Hoe dit te bereiken?
Organiseer de structuur en bepaal het principe voor het kiezen van onderwerpen. De structuur moet zo transparant mogelijk zijn, zodat de lezer niet denkt: “Waar kan ik dit artikel vinden?” Samenvattend zijn er twee benaderingen: vanuit de interface en vanuit de taken.
- Van de interface. De inhoud dupliceert de paneelsecties. Dit was het geval in de oude ISP-systeemdocumentatie.
- Van taken. De titels van artikelen en secties weerspiegelen de taken van de gebruikers; Titels bevatten bijna altijd werkwoorden en antwoorden op de ‘hoe’-vraag. Nu gaan we over op dit formaat.
Welke aanpak u ook kiest, zorg ervoor dat het onderwerp relevant is voor waar gebruikers naar op zoek zijn en dat het op een manier wordt behandeld die specifiek ingaat op de vraag van de gebruiker.
Stel een gecentraliseerde zoekopdracht in. In een ideale wereld zou de zoekfunctie zelfs moeten werken als u een spelfout maakt of een fout maakt met de taal. Onze zoektocht in Confluence tot nu toe kan ons hiermee niet bevallen. Als u veel producten heeft en de documentatie algemeen is, stem dan de zoekopdracht af op de pagina waarop de gebruiker zich bevindt. In ons geval werkt de zoekopdracht op de hoofdpagina voor alle producten, en als je al in een specifieke sectie bent, dan alleen voor de artikelen daarin.
Voeg inhoud en broodkruimels toe. Het is goed als elke pagina een menu en broodkruimels heeft: het pad van de gebruiker naar de huidige pagina met de mogelijkheid om naar elk niveau terug te keren. In de oude ISP-systeemdocumentatie moest je het artikel afsluiten om bij de inhoud te komen. Het was lastig, dus hebben we het in de nieuwe gerepareerd.
Plaats links in het product. Als mensen keer op keer met dezelfde vraag komen helpen, is het logisch om een hint met de oplossing aan de interface toe te voegen. Als u gegevens of inzicht heeft over wanneer een gebruiker een probleem ondervindt, kunt u deze ook op de hoogte stellen via een mailinglijst. Toon hun bezorgdheid en ontlast de steun.
Rechts in het pop-upvenster staat een link naar een artikel over het instellen van DNSSEC in het domeinbeheergedeelte van ISPmanager
Kruisverwijzingen instellen binnen de documentatie. Artikelen die aan elkaar gerelateerd zijn, moeten worden “gelinkt”. Als de artikelen opeenvolgend zijn, zorg er dan voor dat u aan het einde van elke tekst pijlen voorwaarts en achterwaarts toevoegt.
Hoogstwaarschijnlijk zal iemand eerst op zoek gaan naar een antwoord op zijn vraag, niet naar jou, maar naar een zoekmachine. Het is jammer als er om technische redenen geen links naar de documentatie zijn. Zorg dus voor zoekmachineoptimalisatie.
Probleem 4. Verouderde lay-out interfereert met perceptie
Naast slechte teksten kan documentatie ook door ontwerp worden bedorven. Mensen zijn gewend om goed geschreven materiaal te lezen. Blogs, sociale netwerken, media - alle inhoud wordt niet alleen mooi gepresenteerd, maar ook gemakkelijk te lezen en een lust voor het oog. Daarom kun je gemakkelijk de pijn begrijpen van iemand die tekst ziet, zoals in de onderstaande schermafbeelding.
Er staan zoveel screenshots en highlights in dit artikel dat ze niet helpen, maar alleen de perceptie verstoren (de foto is klikbaar)
Je moet geen longread maken van de documentatie met een heleboel effecten, maar je moet wel rekening houden met de basisregels.
Indeling. Bepaal de breedte, het lettertype, de grootte, de kopteksten en de opvulling van de hoofdtekst. Huur een ontwerper in en om het werk te accepteren of het zelf te doen, lees Artyom Gorbunovs boek ‘Typography and Layout’. Het geeft slechts één weergave van de lay-out, maar het is ruim voldoende.
selectie. Bepaal wat in de tekst benadrukt moet worden. Meestal is dit een pad in de interface, knoppen, code-invoegingen, configuratiebestanden, "Let op" -blokken. Bepaal wat de verdeling van deze elementen zal zijn en leg deze vast in de regelgeving. Houd er rekening mee dat hoe minder ontlading, hoe beter. Als het er veel zijn, is de tekst luidruchtig. Zelfs aanhalingstekens veroorzaken ruis als ze te vaak worden gebruikt.
Schermafbeeldingen. Spreek met het team af in welke gevallen screenshots nodig zijn. Het is zeker niet nodig om elke stap te illustreren. Een groot aantal screenshots, incl. aparte knoppen, interfereren met de perceptie, bederven de lay-out. Bepaal de grootte, evenals het formaat van highlights en handtekeningen op screenshots, en leg deze vast in het reglement. Houd er rekening mee dat illustraties altijd moeten overeenkomen met wat er is geschreven en relevant moeten zijn. Nogmaals, als het product regelmatig wordt bijgewerkt, zal het moeilijk zijn om iedereen bij te houden.
Tekstlengte. Vermijd te lange artikelen. Verdeel ze in delen en als dit niet mogelijk is, voeg dan inhoud met ankerlinks toe aan het begin van het artikel. Een eenvoudige manier om een artikel visueel korter te maken, is door de technische details die een kleine kring van lezers nodig heeft, onder een spoiler te verbergen.
formats. Combineer meerdere formaten in je artikelen: tekst, video en afbeeldingen. Dit zal de perceptie verbeteren.
Probeer problemen niet te verdoezelen met een mooie lay-out. Eerlijk gezegd hoopten we zelf dat de "wrapper" de verouderde documentatie zou redden - het lukte niet. De teksten bevatten zoveel visuele ruis en onnodige details dat de regelgeving en het nieuwe ontwerp machteloos waren.
Veel van het bovenstaande wordt bepaald door het platform dat u gebruikt voor documentatie. We hebben bijvoorbeeld Confluence. Ik moest ook met hem sleutelen. Bij interesse, lees het verhaal van onze webontwikkelaar: .
Waar te beginnen met verbeteren en hoe te overleven
Als uw documentatie net zo uitgebreid is als die van het ISP-systeem en u niet weet waar u moet beginnen, begin dan met de grootste problemen. Klanten begrijpen het document niet - verbeter de teksten, maak regelgeving, train schrijvers. Documentatie is verouderd - zorg voor interne processen. Begin met de populairste artikelen over de populairste producten: vraag ondersteuning, bekijk siteanalyses en zoekopdrachten in zoekmachines.
Laten we meteen zeggen: het zal niet gemakkelijk zijn. En het is ook onwaarschijnlijk dat het snel werkt. Tenzij je net begint en meteen het goede doet. Eén ding weten we zeker: het zal in de loop van de tijd beter worden. Maar het proces zal nooit eindigen :-).
Bron: www.habr.com