Kuidas kirjutada abikeskuse artikleid, mida inimesed päriselt kasutavad

autor: Fraser Hardy

Abikeskuse leht otsinguriba, ülesandepõhise artikli pealkirja, numbreeritud sammude ja manustatud tooteekraanipildiga

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:

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

Märgistatud abikeskuse artikli anatoomia: ülesande pealkiri, lühike sissejuhatus, kast Enne alustamist, numbreeritud sammud, ekraanipilt, mis juhtub edasi ja tõrkeotsingu jaotis

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

Enne ja pärast võrdlus: funktsiooni järgi nimetatud artikkel tekstimüüriga, ümber kirjutatud ülesande järgi nimetatud artikliks numbreeritud sammude ja selge tulemusega

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.

  1. Mine jaotisse Seaded > Liikmed.
  2. Klõpsa Lisa liige.
  3. Sisesta tema e-posti aadress.
  4. Vali roll: Admin, Toimetaja või Vaataja.
  5. 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.

Avaldatud abikeskuse artikkel ülesandepealkirja, ühe rea sissejuhatuse ja manustatud ekraanipildiga täpselt sellest ekraanist, mida lugeja vaatab

Mida kirjutada esimesena

Kui alustad nullist, ära püüa dokumenteerida iga funktsiooni. Kirjuta selles järjekorras:

  1. Esimesed viisteist minutit. Registreerumine, esimene seadistussamm, esimene “oh, see on kasulik” hetk. Iga uus kasutaja loeb neid.
  2. Sinu kõige sagedasemad tugiküsimused. Käi läbi oma postkast. Kõik, millele oled sel kuul kolm korda vastanud, saab artikli.
  3. 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.
  4. Integratsioonid. Kolmanda osapoole kontode ühendamine on koht, kus inimesed jäävad kinni ekraanidel, mida sa ei kontrolli.
  5. 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.

Abikeskuse sisupuu, rühmitatud kogumikeks nagu Alustamine ja Vastuste parandamine, millest igaühes on lühikesed ülesandenimedega artiklid

Abidokumentatsiooni kirjutamine: väikesed harjumused, mis liituvad

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:

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.

Ellie Docsi artiklite redaktor, mis näitab koostatud abiartiklit automaatselt jäädvustatud tooteekraanipildi ja funktsioonidega, millel artikkel põhineb

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.