Kuidas kirjutada abikeskuse artikleid, mida inimesed päriselt kasutavad
Keegi kirjutab sinu abikeskuse otsingusse “arvete eksport”. Ta saab kolm tulemust: “Arvelduse ülevaade”, “Aruanded” ja “Andmetega alustamine”. Ükski neist ei ütle eksport. Ta sulgeb vahelehe ja kirjutab sulle e-kirja.
See ongi enamiku abikeskuse artiklite probleem. Need on korraldatud selle järgi, kuidas toode on ehitatud, mitte selle järgi, mida inimesed teha püüavad.
Nii et siin on lühike vastus. Selleks et kirjutada abikeskuse artikleid, mida inimesed päriselt kasutavad: nimeta iga artikkel ühe ülesande järgi kliendi sõnadega, ütle ühe reaga, mida see teeb, loetle kõik, mida nad peavad enne vajama, anna numbreeritud sammud, kus igaühes on üks tegevus, lisa ekraanipilt kohta, kus inimesed tavaliselt eksivad, ja lõpeta sellega, mida nad peaksid nägema, kui see õnnestus. Üks artikkel, üks ülesanne. Kui tabad end kirjutamas “saad ka”, on see tõenäoliselt teine artikkel.
Ülejäänud postitus on detailid: mall, mida saad kopeerida, enne ja pärast ümberkirjutus, mida kirjutada esimesena ja kuidas hoida see kõik kuus nädalat pärast käivitamist aegumast.
Mis teeb hea teadmusbaasi artikli?
Keegi ei loe abidokumentatsiooni lõbu pärast. Inimesed saabuvad ülesande keskel, veidi ärritununa, tavaliselt otsingust (sinu enda või Google’i) või lingilt, mille keegi sinu meeskonnast vastusesse kleepis. Nad skaneerivad. Nad tahavad leida sammu 3, selle teha ja lahkuda.
Seega on hea teadmusbaasi artikkel selline, mis laseb skaneerival, veidi ärritunud inimesel oma ülesande lõpule viia, midagi kaks korda lugemata. Praktikas tähendab see:
- Üks artikkel, üks ülesanne. “Kutsu meeskonnakaaslane” ja “Muuda meeskonnakaaslase rolli” on kaks artiklit. Need viitavad üksteisele.
- Pealkirjad näevad välja nagu otsingupäringud. Inimesed otsivad tegusõnadega: “tühista tellimus”, “lähtesta parool”, “ühenda Slack”. Sinu pealkirjad peaksid kõlama samamoodi.
- Sammud on numbreeritud ja aatomilised. Üks klõps või üks väli sammu kohta. Kui samm sisaldab “ja siis”, jaga see.
- Täpsed kasutajaliidese sildid paksus kirjas. Kui nupp ütleb Lisa liige, ära kirjuta “klõpsa kutsumise nuppu”. Lugeja sobitab ekraanil olevaid sõnu sinu artikli sõnadega.
- See lõpeb tulemusega. “Nad ilmuvad liikmete nimekirja märgiga Ootel, kuni nad kutse vastu võtavad.” See rida ütleb inimestele, et nad on valmis, ja see on rida, mille enamik kirjutajaid välja jätab.
Diátaxise raamistik jagab dokumentatsiooni õpetusteks, juhenditeks, viideteks ja selgitusteks. Enamik abikeskuse artikleid peaksid olema juhendid. Levinud viga on kõigi nelja segamine ühele lehele, nii et sammu 4 otsiv inimene peab läbi vaeva nägema kolm lõiku selle kohta, miks funktsioon üldse olemas on.
Abikeskuse artikli mall, mida saad kopeerida
See on mall, millest alustaksin iga ülesandeartikli. See töötab Zendeskis, Intercomis, Help Scoutis, GitBookis või Markdown-failide kaustas sinu repositooriumis.
# [Verb] [the thing]
<!-- e.g. "Export your invoices to CSV" -->
[One or two sentences: what this does and when you'd want it.
Mention the plan or role if it's restricted.]
**Before you start**
- You need [role or permission], e.g. Admin or Owner
- [Anything to have ready: a file, an API key, a connected account]
## Steps
1. Go to **[Page name]** in the left sidebar.
2. Click **[Exact button label]**.
3. In **[Field name]**, enter [what, with an example value].
4. Click **[Confirm button label]**.
<!-- Screenshot of the step where people get stuck.
Crop to the relevant area, highlight the target. -->
## What happens next
[What they'll see when it worked. How long it takes.
Who gets notified.]
## If it didn't work
- **[Symptom in the customer's words]**: [cause and fix]
- **[Second most common symptom]**: [cause and fix]
## Related
- [The task people usually do next]
- [The reverse task, e.g. "Remove a teammate"]
Mõned märkused selle kasutamise kohta.
Sissejuhatus ei ole müügikõne. “Meie võimas eksportimisfunktsioon annab sulle täieliku kontrolli oma andmete üle” ei ütle lugejale midagi. “Laadi alla kõik kuupäevavahemiku arved CSV-failina, mida saad avada Excelis või Google Sheetsis” ütleb talle, kas ta on õigel lehel.
”Enne alustamist” hoiab ära kõige rohkem tugipileteid. Klassikaline ebaõnnestumine: keegi järgib kuut sammu ja saab alles seitsmendal teada, et seda saavad teha ainult administraatorid. Pane load ja plaanipiirangud ülaossa, mitte märkusena lõppu.
”Kui see ei õnnestunud” peaks tulema päris piletitest. Ära mõtle tõrkeotsingut välja. Vaata läbi viimase kuu klienditoe e-kirjad ja pane kirja, kus inimesed tegelikult kinni jäid. Kaks-kolm punkti on piisavalt. Kui tahad selleks korratavat viisi, kirjutasime eraldi juhendi teemal tugipiletite muutmine abiartikliteks.
Enne ja pärast: tüüpilise abiartikli ümberkirjutamine
Siin on selline artikkel, mis kirjutatakse nädalal, kui funktsioon välja tuleb. Toode on väljamõeldud, muster mitte.
Meeskonna haldus
Meie meeskonnahalduse funktsioon teeb koostöö lihtsaks. Seadete alalt saad hallata oma meeskonda, sealhulgas lisada uusi liikmeid vahekaardil Liikmed, kus leiad nupu Lisa liige, ja valida rolle nagu Admin, Toimetaja või Vaataja, mis kontrollivad, millele igaüks juurde pääseb. Kutsutud kasutajad saavad e-kirja. Pane tähele, et liikmeid saavad lisada ainult adminid ja kohtade arv sõltub sinu plaanist.
Kõik, mida lugeja vajab, on seal sees. See on vales järjekorras, pealkirja all, mida keegi ei otsi, ja loa konks on viimane lause.
Siin on ümberkirjutus:
Kutsu meeskonnakaaslane
Lisa keegi oma tööruumi, et ta saaks projekte vaadata ja muuta.
Enne alustamist: sa pead olema admin. Iga inimene kasutab ühe koha sinu plaanis. Näed, mitu kohta sul veel alles on, jaotises Seaded > Arveldus.
- Mine jaotisse Seaded > Liikmed.
- Klõpsa Lisa liige.
- Sisesta tema e-posti aadress.
- Vali roll: Admin, Toimetaja või Vaataja.
- Klõpsa Saada kutse.
Mis juhtub edasi: nad saavad e-kirjaga kutse. Kuni nad selle vastu võtavad, kuvatakse neid liikmete nimekirjas märgiga Ootel.
Kui see ei õnnestunud: kui Lisa liige on hallikas, oled kõik kohad ära kasutanud. Eemalda keegi või lisa kohti jaotises Seaded > Arveldus.
Samad faktid, ligikaudu sama pikkus. Aga pealkiri vastab sellele, mida inimesed kirjutavad, konks on ees, iga samm on üks tegevus ja lugeja teab, millal ta on valmis. Rollide selgitused liikusid oma lühikesse artiklisse (“Mida iga roll teha saab”), millele viidatakse sammust 4.
Kui pikk peaks abikeskuse artikkel olema?
Nii pikk kui ülesanne ja mitte pikem. Rusikareeglina jääb ühe ülesande juhend kuhugi 150 ja 500 sõna vahele. Kui oled sellest tublisti üle, kontrolli, kas oled kokku liimitud kaks ülesannet või triivinud funktsiooni filosoofia selgitamise juurde.
Erand on seadistusjuhendid, nagu “Ühenda oma Shopify pood”, kus on tõesti tosin sammu kahes süsteemis. Need võivad olla pikad, kui jaotad need H2-sektsioonideks, kuhu inimesed saavad hüpata.
Kus ekraanipildid aitavad ja kus kahjustavad
Ekraanipildid on see, mida lugejad märkavad kõige rohkem ja mida meeskonnad hooldavad kõige vähem.
Kasuta ühte seal, kus kasutajaliides on mitmetähenduslik: rahvarohke seadistuste leht, modaalaken kuue väljaga, nupp, mis ei ole seal, kus inimesed seda ootavad. Jäta need vahele “klõpsa Salvesta” puhul. Kärbi tihedalt olulise ala järgi ja tõsta sihtmärk esile, kui ekraan on tihe.
Konks on see, et iga ekraanipilt on lubadus, et kasutajaliides näeb ikka niimoodi välja. Liiguta menüüd ja sul on kümneid artikleid, mis näitavad vaikselt klientidele ekraani, mida enam ei eksisteeri. See on peamine argument nende automatiseerimiseks, selle asemel et neid käsitsi teha. Võrdlesime võimalusi (Playwrighti skriptid, ekraanisalvestajad, tööriistad, mis need sinu eest jäädvustavad) artiklis kuidas ekraanipilte automaatselt luua.

Mida kirjutada esimesena
Kui alustad nullist, ära püüa dokumenteerida iga funktsiooni. Kirjuta selles järjekorras:
- Esimesed viisteist minutit. Registreerumine, esimene seadistussamm, esimene “oh, see on kasulik” hetk. Iga uus kasutaja loeb neid.
- Sinu kõige sagedasemad tugiküsimused. Käi läbi oma postkast. Kõik, millele oled sel kuul kolm korda vastanud, saab artikli.
- Kõik, mis puudutab raha või andmeid. Arvelduse muutused, tühistamine, kustutamine, eksportimine. Inimesed on siin närvilised ja tahavad kindlust, mitte ebamäärast lõiku.
- Integratsioonid. Kolmanda osapoole kontode ühendamine on koht, kus inimesed jäävad kinni ekraanidel, mida sa ei kontrolli.
- Kõik muu, ligikaudu selles järjekorras, kui sageli inimesed sellega kokku puutuvad.
Rühmita need käputäieks kogumikeks, mis on nimetatud nii, nagu kliendid mõtlevad: “Alustamine”, “Arveldus ja konto”, “[Sinu põhifunktsiooni] kasutamine”, “Integratsioonid”, “Tõrkeotsing”. Väldi kogumikke, mis peegeldavad sinu sisemist meeskonnastruktuuri.

Abidokumentatsiooni kirjutamine: väikesed harjumused, mis liituvad
- Kirjuta teises isikus ja olevikus: “Klõpsa”, “Näed”.
- Kasuta toote päris silte, isegi neid, mida pead halvasti nimetatuks. Siis mine ja paranda silt.
- Hoia lõigud kahe-kolme lauseni.
- Kasuta märkuseplokke säästlikult. Märkus millegi kasuliku jaoks, hoiatus millegi pöördumatu jaoks. Kui igal artiklil on kolm hoiatust, lõpetavad inimesed nende nägemise.
- Näita, millal artiklit viimati uuendati, et lugejad (ja sina) näeksid, kui värske see on.
- Lingi edasi. Iga artikkel peaks viitama sellele, mida inimesed tavaliselt järgmisena teevad.
Google’i arendajadokumentatsiooni stiilijuhend on suunatud tehnilisele dokumentatsioonile, kuid enamik selle nõuandeid selguse ja hääle kohta toimib sama hästi klientidele suunatud abi puhul.
Osa, mida keegi ei planeeri: artiklite täpsena hoidmine
Artikli kirjutamine on lihtne osa. Raske osa on see, et sinu toode muutub igal nädalal ja sinu abikeskus mitte.
Olenemata tööriistast aitavad mõned asjad:
- Märgi iga artikkel funktsiooni või ekraaniga, mida see katab, et kui see funktsioon muutub, tead täpselt, milliseid artikleid kontrollida.
- Tee “dokumentatsioon kontrollitud” osaks valmisoleku definitsioonist iga PR-i puhul, mis muudab kasutajaliidese teksti või kasutajavoogu.
- Loe oma enim külastatud artikleid umbes kord kuus uuesti. Just seal teeb aegunud ekraanipilt kõige rohkem kahju.
- Jälgi otsinguid, mis ei anna tulemusi. See on tasuta nimekiri artiklitest, mida sa pole veel kirjutanud.
Käsitleme seda korralikult artiklis kuidas dokumentatsiooni ajakohasena hoida, sealhulgas selle kohta, kuidas siduda dokumentatsiooni ülevaatus sinu väljalaskeprotsessiga. Ja kui avaldad väljalaskemärkmeid, kehtib seal sama distsipliin: vaata kuidas kirjutada muudatuslogi, mida kliendid päriselt loevad.
Kus Ellie Docs sobib
Avalikustamine: me ehitame selleks tööriista. Ellie Docs ühendub sinu GitHubi repositooriumiga, loeb koodi, et välja selgitada sinu funktsioonid ja kasutajale suunatud ekraanid, ning koostab täieliku abikeskuse mustandi. See käivitab sinu rakenduse liivakastis, jäädvustab sisseloginud toote tõelised ekraanipildid ja paigutab need artiklitesse.

Osa, mis mulle kõige rohkem korda läheb, on hooldus. Kui PR ühendatakse, kontrollib Ellie, milliseid artikleid muudatus mõjutab, ja pakub muudatusi välja diffina, mille sa kas aktsepteerid või lükkad tagasi. Miski ei avaldu ise. Sina otsustad ikka, mida kliendid loevad, sa lihtsalt lõpetad tugipiletist teada saamise, et samm 6 on kuu aega vale olnud.
Kui sul on abikeskus juba olemas, impordib see sinu olemasolevad artiklid mustanditena, nii et sa ei alusta nullist. Tasuta plaan on olemas, kaarti pole vaja.
Ja kui eelistad kõike käsitsi teha, töötab ülaltoodud mall ka ise hästi.
Mõned küsimused, mida inimesed esitavad
Mis vahe on abikeskusel ja teadmusbaasil? Praktikas mitte palju. “Teadmusbaas” tähendab tavaliselt artiklite kogumit ja “abikeskus” kliendile suunatud saiti, mille peal on otsing ja navigatsioon. Enamik tööriistu kasutab termineid vaheldumisi.
Kes peaks abiartikleid kirjutama: klienditugi, toode või insenerid? Kes iganes on küsimustele kõige lähemal. Klienditugi teab, mis inimesi segadusse ajab, insenerid teavad, mis muutus. Hästi töötav lahendus on see, kus klienditugi omab abikeskust ja insenerid märgivad oma PR-ides mõjutatud artiklid.
Tahad oma koodibaasist kirjutatud abikeskuse esimest mustandit? Proovi Ellie Docsi tasuta ja vaata, mida see sinu repositooriumist toodab.