Anbefalinger til dokumentation

Jeg elsker at skrive dokumentation.

Overordnet som fx. denne præsentation og dobbelte installationsvejledning til Drupal-modulet Wayback Filter. Men også helt ned til bittesmå, koncise hjælpetekster, der under et postnummer-felt fortæller brugeren, hvilke data systemet forventer og godtager.

Fejlmeddelelser får mig også til at tralle. Morsomme, unikke, handlingsanvisende. Det kan godt lade sig gøre!

Så er der folk, der laver betalingsløsninger.

Sinker. Hele bundtet. De sløser helt ekstremt med dokumentation, hjælptekster, fejlmeddelser, eksempler og testmuligheder.

I løbet af det seneste år har jeg integreret betalingsløsninger fra PayPal, Moneris, Stripe og Quickpay på kundernes websider. Og alle betalingsløsningerne har uden undtagelse budt på ufuldstændig, fejlbehæftet dokumentation og eksempler, der ikke virkede i virkeligheden.

Lad os tage ét eksempel ud af over 50.

Fra QuickPays hjemmeside <

Hvor mange fejl er der i denne ene sætning?

The autocapture is send from the shop weather you are using a shopsystem this option will be in the Quickpay plugin and for custom made you need to send auto_capture in the payments link request See here

De første fejl, der rammer øjet, er sent og whether stavet forkert. Skulle det være korrekt engelsk, burde shopsystem nok også deles.

Men selv hvis man sætter whether ind i stedet for wheather, falder sætningen stadigvæk helt sammen. Prøv at læse hele sætningen højt. Den er dårlig tænkt.

Der ville komme mere skik på den med

If you are using a shop system (list of all known shop systems using Quickpay), autocapture should be a part of the system. Refer to the documentation of the shop system or ask the provider of the shop system for assistance.

If you are making a custom integration, use the Create or update a payment link call to autocapture. See our Advanced Quickpay Link example.

Så er det pludselig korrekt engelsk og læseren kan komme nyttige steder hen.

Det vil sige. Ikke helt. Sidste link, Advanced Quickpay Link example, går til et, i skrivende stund, simpelt, skrabet og mangelfuldt eksempel. I en bedre verden ville Quickpay både byde på et simpelt eksempel (så folk kunne eftergøre og teste hurtigt) og et avanceret eksempel (så de med lethed kunne se den rette syntaks for alt og teste hurtigt).

Min version af sætningen fylder dobbelt så meget. Men den tager kun 4 sekunder længere at læse. Og læseren sparer TIMER, fordi der er

• Klar tanke og tale
• Nyttige links med brugbare titler
• Nyttige forslag og gode eksempler i den anden ende af mine links.

Og det er ved Gud bedre, at 30.000 kunder sparer 1 time, end at 1 dokumentationsskriver sparer 3 minutter ved at levere noget næsten link-løst og delvist ubrugeligt sludder.

Hvad mangler Quickpay for at kunne skrive ordentlig dokumentation?

Penge? <

Nej! Quickpay har haft millionoverskud i årtier. At de ikke gider ofre 20-30.000 kr. på at forvandle deres dokumentation fra skidt stavet vrøvl til brugbar dokumentation, kan næsten ikke være økonomisk betinget.

Uvidenhed? <

Næppe. Jeg - og formentlig mange andre kunder - har klaget over dokumentationskvaliteten ved flere lejligheder og stillet Quickpay Support-spørgsmål, som en bare 20% bedre dokumentation ville have besvaret. Næsten gratis. Før problemerne opstod.

Den dårlige dokumentation kan næsten heller ikke skyldes manglende erfaring eller talent. QuickPay har ansat mange kvikke mennesker og deres Support har i de snart 20 år, jeg har brugt den, været både kvik og velformuleret. Dertil sympatisk.

Så min teori er, at det er gælder særlige regler for betalingsformidlere.

De er uomgængelige og det er ret dyrt, i timer og anstrengelse, for kunderne at skifte. Så kunderne finder sig i hvad som helst og bander sjældent offentligt.

 - QuickPay er i øvrigt slet ikke de værste. Deres dokumentation er faktisk mærkbart bedre end den man får hos PayPal, Stripe og Moneris. QuickPay er dertil hædersmænd m/k i forhold til de uredelige stympere hos PayPal og Stripe.

Nuvel.

Skriv også dokumentation for din egen skyld <

Hver gang vi i Vertikal skriver et modul til Drupal, skriver vi en fornuftig installationsvejledning. Selv hvis det ikke skal udgives offentligt.

For hvem ved om vi, eller nogle andre, skal installere det et nyt sted? Hvorfor skulle vi gå også huske vigtige detaljer om konfigurationen af alle moduler og i hvilken sekvens man tænder for forskellige dele?

Det er bedre at have det på skrift.

Helt ned på kodeniveau fortæller vi os selv - og andre - hvad de forskellige funktioner laver og hvad man skal være opmærksom på.

Dokumentation skal derhen hvor den gør nytte. Ikke være noget man måske får ud af flygtige telefonsamtaler eller måske finder et sted i mail-bunken.

Så.

Hvordan gør jeg min dokumentation bedre? <

Gør som du har lært i skolen.

1. Skriv enkle, korte sætninger.
2. Link til yderligere, nyttige forklaringer. Link alle steder, hvor brugeren kan få glæde af det. Se hvor meget eksemplet ovenfor blev forbedret af få, korrekte links!
3. Billeder. Når et billede siger mere end 1.000 ord, bruger du et billede. Prop pile på dine illustrationer.
4. Hav en konsekvent sprogbrug. Et kald er altid et kald, aldrig en funktion eller forespørgsel. Folk bryder sig ikke om sprogforvirring.
5. Tænk proces. Forestil dig, at du tager læseren ved hånden, og leder dem frem mod målet. "Så tager du kniven og deler rouladen midt over. Du har nu to lige store stykker". Fortæl dem både hvad de skal gøre, hvordan de skal gøre det og hvad de ser, når de har gjort det. Både hvad de ser, hvis de har gjort det korrekt, og hvad de ser, hvis de har gjort det ukorrekt.
6. Eksemplerne skal være rigelige og, hvor det giver mening, delt i simple og avancerede. Ros til QuickPay (og mange andre) for at tilbyde eksempler på flere programmeringssprog (at deres Quickpay Link eksempel så er et tavst, begrænset eksempel af begrænset nytte, piner mig selvfølgelig).
7. Husk at ingen gider læse lange, uoverskuelige dokumentationsdokumenter. 120 siders PDF fra Moneris er mere øjentjeneri, end det er moderne hjælp til kunderne. Brug hypertekst, links, alle tricks i bogen. Det fleste hypertekstløsninger er bedre end lange PDF-dokumenter i A4-format. Men tilbyd også PDF-versioner, hvis du har mærkelige kunder, der elsker at spilde tid.
8. Hjælpeteksterne under felter (og over knapper) skal være mange, handlingsanvisende, løftegivende. "Indtast dansk, firecifret postnummer. Eksempel: 2400.".
9. Fejlmeddelelserne skal være specifikke og handlingsanvisede. "Postnummer: kun tal. Præcis fire." Hos betalingsudbydere drømmer jeg stadig om brugbare fejlmeddelelser og testmiljøer.
10. En wizard (opsætningshjælper) er også tit bedre end langtrukken dokumentation.
11. Bed ChatGPT forbedre din dokumentation. Det lykkes måske ikke, men I finder måske nogle ting, du alligevel får lyst til at forbedre.

Kort sagt: simpel tekst, mange links, brugbare eksempler/testmiljøer og lad specifikke og handlingsanvisende hjælpetekster og fejlmeddelelser trække det store læs.

Det tager lidt tid at skrive bedre dokumentation. Men 3 minutter for 1 mand, kan spare 30.000 timer for 30.000 mand.

Verden bliver bedre og rigere af god dokumentation.