Hvordan man skriver gode artikler

Det er vores hellige pligt (svage englekor) at holde det nemt at navigere og gøre hver artikel super godt beskrevet, så det forbliver et essentielt værktøj til at bygge bro mellem Produkt og resten af virksomheden.

Hver artikel, du skriver, vil potentielt blive læst hundrede, hvis ikke tusinder af gange, så du må være besat af kvaliteten.

Skrive Stil #

Hvor svært kan det være at skrive dokumentation? Du skriver nogle ord ned, der viser, hvor man skal gå hen, og tilføjer et screenshot, ikke?

Nå, ja og nej. Mest nej faktisk.

Hvordan vi skriver dokumentation er lige så afgørende som hvad vi skriver. Det er grundlæggende UX’en i vores arbejde.

Tænk trods alt på de vigtigste grunde til, at Apple er et af de førende elektronikfirmaer i verden. De laver bare telefoner og bærbare computere, ikke?

Ja, men de laver dem også i en super skarp og ensartet kvalitet, der skaber næsten religiøse grupper af mennesker, der sværger til deres økosystem.

Design betyder noget, og designet af en Knowledge Center artikel er skrivestilen.

Dette skal være konsekvent fantastisk, så kolleger og kunder bliver lige så religiøst investerede i at bruge det, som vi ønsker, de skal være ;)

Lad os dykke ned i, hvordan du kan gøre dette.

Stemme & Tone #

Når vi skriver til vores kunder, fokuserer vi på at gøre tingene klare og lette at forstå. Vores mål er at give dem nyttige oplysninger uden at forvirre dem. Vi undgår kompliceret sprog og sørger for, at hvert nødvendigt trin er forklaret.

Vi skriver til både tekniske og ikke-tekniske læsere, så vores artikler skal være enkle, men informative for begge typer læsere. Vi gør dette gennem fremragende tekst og en klar struktur.

Humor er velkommen, men kun hvis det passer naturligt. Det vigtigste er, at vi ønsker at hjælpe vores kunder uden at tale ned til dem eller antage, at de ved alt.

1. Hold det simpelt: Brug klart, letforståeligt sprog. Undgå lange, forvirrende sætninger og komplicerede ord. Brug aktiv stemme for at gøre skrivningen direkte og let at læse.

2. Vær respektfuld: Skriv på en måde, der behandler læseren som en ligemand. Antag ikke, at de allerede ved tingene. Sørg for at give alle de detaljer, de har brug for, med links til mere info, hvis nødvendigt.

3. Vær klar og hjælpsom: Fokuser på at give nyttige oplysninger i stedet for lange forklaringer. Guid læserne trin-for-trin, og tænk over, hvad de måske søger, så de nemt kan finde svarene.

4. Brug humor med omhu: Humor er fantastisk, hvis det passer naturligt, men det bør aldrig være tvunget. Hvis du ikke er sikker på, om det virker, så lad det være ude. Hold fokus på at være hjælpsom og klar.

Vores tone er uformel med stort fokus på klarhed. Humor opfordres, men kun hvis det passer til den sindstilstand, en bruger har, når de læser det. Tænk over, hvorfor brugerne er her. Hvis en bruger læser en artikel, der forklarer, hvordan Søgning fungerer, er de sandsynligvis i en opdagelsestilstand, og humor kan fungere godt.

Men hvis de gennemser FAQs eller fejlfindingartikler, er de sandsynligvis allerede irriterede over et problem og har blot brug for en klar løsning. Sindstilstand betyder noget ;)

Når humor bruges, gør det nørdet - Vi elsker referencer til Star Wars, Ringenes Herre, The Matrix og andre nørdekultur fænomener. Det fungerer ofte meget godt i kodeeksempler, som du vil se ;)

Typer af artikler #

Når du skriver, skal du overveje, hvilken af disse typer der bedst løser brugerens behov.

Informativ #

Forklarer begreberne i et produkt eller en funktion. Læsere er normalt i opdagelsestilstand, når de læser disse og ønsker at forstå, hvordan det fungerer. Disse artikler inkluderer ikke trin eller grundig vejledning gennem backend, men forklarer klart, hvordan hver del fungerer.

Eksempler:

• Cookieless
• Dashboard
• Samtaler

How-Tos #

Forklarer, hvordan man opnår et bestemt resultat. Disse kræver trin-for-trin vejledning, der forklarer de præcise knapper, som brugerne skal klikke på, og konfigurationer, de skal gennemgå. Læsere forsøger normalt at opnå noget specifikt, når de læser disse.

Eksempler:

• Kom i gang med Shopify
• Anbefalinger Bedste Praksis
• Tilføj en ny butik

FAQs / Fejlfinding #

Forklarer de mest sandsynlige løsninger på almindelige spørgsmål eller problemer. Læsere er ofte frustrerede i en eller anden grad, når de gennemser disse, fordi noget ikke fungerer som forventet. Disse bør være klart mærket med det spørgsmål, en læser vil have i tankerne, og give klare forklaringer på, hvordan man løser det.

Disse er aldrig individuelle artikler, men samles under FAQ for et specifikt produkt, funktion eller integration.

Eksempler:

• Any Webshop FAQ
• Lightspeed 429 Fejl
• Magento 2 403 Forbidden Fejl

Intros #

Bemærk hvordan denne artikel og sektionerne om Skrive Stil starter med en lille intro? Læg mærke til, hvad de opnår?

Intros handler om at forklare hvorfor noget er vigtigt at læse. Det handler om at fange læserens opmærksomhed og lade dem hurtigt spotte, om de har fundet indholdet eller ej.

Intros bør ikke være for lange, men de bør give læserne konteksten for, hvad de er ved at læse.

Inkluder altid intros i begyndelsen af artikler og når du starter nye sektioner med en h2 overskrift.

Titel & Beskrivelse #

Titlen på din artikel skal altid være klar og kortfattet. En god titel indeholder maksimalt 3 ord, og ideelt set kun 1.

En god titel er “Omnisearch”. En dårlig version er “Vores Omnisearch Funktion”. Den tilføjer for mange unødvendige ord og gør det sværere at navigere i menustrukturen.

Korte titler fungerer godt, fordi de er lette at gennemse, og kombineret med en logisk menustruktur holder vi Knowledge Centeret nemt at navigere.

Artikeltitler bør være en enkelt sætning, der tilføjer kontekst til artiklen. Det hjælper læserne med at validere, om denne artikel er, hvad de ledte efter. Undgå at gentage titlen i din beskrivelse - den bør supplere den.

En god beskrivelse for Omnisearch er: “Et enkelt fuldskærmsvindue, der giver dine besøgende de resultater, der sandsynligvis vil konvertere”. Det uddyber klart, hvad Omnisearch er, i en enkelt sætning.

En dårlig en er: “Omnisearch er en ny funktion i vores søgeprodukt”. Den gentager navnet på funktionen og dens placering i vores katalog, hvilket allerede er klart fra menuen i Knowledge Centeret.

Overskrifter #

Disse er afgørende for at gøre artikler lette at skimmede og navigere. Brug dem til klart at adskille forskellige dele.

Overskrifter er hierarkiske og bruges altid i følgende rækkefølge:

• h1: Bruges kun af titlen
• h2: Hovedsektion
• h3: Undertitel til h2
• h4: Undertitel til h3

Vi bruger aldrig overskrifter mindre end h4.

Alle h2’ere og h3’ere bruges automatisk til at oprette indholdsfortegnelsen.

Afsnit #

Når vi skriver artikler, ønsker vi, at læserne skal kunne navigere og forstå dem let. Trods alt vil de sjældent læse hele artiklen, men skimmede igennem den for at finde de dele, de har brug for.

Det ideelle afsnit er mellem 1-3 linjer. Længere afsnit ender hurtigt med at se ud som vægge af tekst. Når du skriver, skal du sørge for, at det er let at skimmede ved at tilføje linjebrud efter mindst hver 3. linje (når det ses på en 13 tommer bærbar computer).

Dette er ikke et strengt krav, men en god tommelfingerregel. Vores hjerner har tendens til at se på store tekstblokke og konkludere, at de er svære at læse, selvom de ikke er.

For at visualisere forskellen, tjek sektionen nedenfor, hvor linjebruddene er blevet fjernet. Sværere at skimmede, ikke?

Når vi skriver artikler, ønsker vi, at læserne skal kunne navigere og forstå dem let. Trods alt vil de sjældent læse hele artiklen, men skimmede igennem den for at finde de dele, de har brug for. Det ideelle afsnit er mellem 1-3 linjer. Længere afsnit ender hurtigt med at se ud som vægge af tekst. Når du skriver, skal du sørge for, at det er let at skimmede ved at tilføje linjebrud efter mindst hver 3. linje (når det ses på en 13 tommer bærbar computer). Dette er ikke et strengt krav, men en god tommelfingerregel. Vores hjerner har tendens til at se på store tekstblokke og konkludere, at de er svære at læse, selvom de ikke er. For at visualisere forskellen, tjek sektionen ovenfor, hvor linjebruddene er blevet tilføjet. Lettere at læse, ikke?

Links #

Når det giver mening, skal du inkludere links til andre dele af Knowledge Centeret. Husk, at brugeren skal have alt, hvad de har brug for, i en enkelt artikel, så det er ofte værd at opsummere punkterne, før du linker til en anden artikel med mere info.

Eksempel:

Før du fortsætter, skal du sørge for at oprette en ny indholdsblok. Du kan gøre dette fra Recommendations > Content > Create New. Læs mere om Indhold her.

Screenshots #

Vi bruger Brandbird til at skabe flotte screenshots. Inkluder altid en god kontrastbaggrund til dit screenshot, der ikke stjæler opmærksomheden, men supplerer det.

Screenshots er vigtige, fordi de viser læseren, at de er det rigtige sted i vores backend. Så deres hovedformål er at give kontekst, ikke at vise hver interaktion. Copywriting gør det.

En god tommelfingerregel er at inkludere maksimalt det samme antal billeder, som du har h2 og h3 overskrifter. Færre er også okay - ofte er mindre mere, når det kommer til screenshots.

Tjek hvordan Linear bruger screenshots sparsommelig, og bruger god copywriting til at supplere dem.

Et screenshot bør generelt dække hele omfanget af en side, efterfulgt af tekst, der forklarer de skridt, der skal tages, eller de funktioner, der er tilgængelige.

F.eks. i stedet for at vise 3 forskellige billeder for HTML, CSS og Sub-Designs separat, er et enkelt, der viser det hele i det indledende afsnit bedre. Annotationer er også velkomne for at hjælpe med at afklare dele af et billede.

Videoer #

Vi bruger Loom eller Tella til at optage videoer. Brug deres respektive Embed funktioner og husk altid at vælge den Responsive version. De kan tilføjes direkte til en artikel som dette:

Videoer er gode til klart at vise alle aspekter af en funktion eller hvordan man gør noget specifikt. De supplerer vejledninger godt, da læserne ofte kan starte med at se videoen, før de bruger artiklen som reference.

Videoer bør dog aldrig erstatte skrevet tekst, så alt, der vises i en video, bør også skrives i tekst.

Når du optager videoer, skal du gennemgå punkterne kronologisk i den samme rækkefølge, du skrev artiklen i, så de er lette at følge.

Menu Elementer #

Vi organiserer Knowledge Centeret logisk, og generelt i den samme rækkefølge, som funktionerne vises i vores backend.

Kun artikler, der er relevante for alle kunder, bør have deres egne sider. Eventuelle kanttilfælde bør tilføjes under FAQs for det relevante aspekt.

Eksempler:

• Artikler, der forklarer, hvordan Omnisearch fungerer, er relevante for alle kunder, der bruger produktet, så den har sin egen artikel.
• Fejlfinding af, hvorfor sporbare ordrer ikke vises i dashboardet, er et kanttilfælde og placeres i FAQ for Any (Webshop)

Hugo #

Hele vores Knowledge Center er skrevet ved hjælp af Hugo Themes - Et letvægts templateringssystem, der genererer statiske HTML-filer fra Markdown. Det giver os mulighed for at arbejde helt i /content mappen, og Hugo gengiver det hele smukt gennem vores tema.

Tjek hvordan du kommer i gang med Hugo i README.md filen, der findes i roden, eller i Github repo.

Mapper & filer #

Du arbejder i content/en mappen og i integrations- og platform undermapperne.

Oversættelser håndteres af Localazy, som du kan se fra README.md filen i roden.

Filstrukturen ligner tæt menustrukturen, fordi Hugo gengiver menuen baseret på den mappestruktur, du ser nedenfor.

Hver artikel er i sin egen mappe med en _index.md fil, som du redigerer. Underskuddet skal inkluderes for at Hugo kan forstå, at dette er en landingsside.

Som standard defineres titlen på en artikel af mappenavnet, så vælg det omhyggeligt og følg de eksisterende eksempler. Titlen kan overskrives i front matter for hver artikel.

root/
├── archetypes/
├── assets/
├── content/
│   └── en
│        └── integrations
│            └── act-on
│                └── email-recs
│                    ├── _index.md
│                    ├── screenshot_10535...
│        └── platform
│        └── search (søgesidefilen)
│        └── writing (denne artikel)	
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- site konfiguration

URL’en for hver artikel genereres baseret på mappestrukturen ned til det sidste lag, hvor _index.md filen er. URL’en for ovenstående eksempel er /integrations/act-on/email-recs

Front Matter #

Dette er metadata, du kan tilføje til artikler, såsom titler, beskrivelser, aliaser (omdirigeringer), kategorier og mere.

Front matter findes altid i toppen af en artikel:

---
title: "Holy Grail"
onPageTitle: "Hvordan man finder den Hellige Gral"
description: "Monty Pythons bedste film langt"
weight: 3
aliases:
   - /old/path/to/holy-grail
   - /really/old/path/to/holy-grail
---

Hvad er hastigheden af en ubebygget svale?...

Den vigtigste front matter er:

• title: En tilpasset titel til artiklen, der bruges til at tilpasse dens menupunkt. Hvis dette ikke er inkluderet, vil den titlerede mappenavn blive brugt.
• onPageTitle: En titel, der kun vises på artikel siden, ikke i menuen. Dette er godt for SEO-formål, hvor sidetitel kunne være “Hvordan Produktlogikker fungerer”, mens artiklen stadig er listet som “Logikker” i menuen.
• description: Vist lige under titlen på artikel siden. Dette er påkrævet, da det giver værdifuld kontekst til læseren.
• weight: Artiklens position i menuen. Jo lavere nummeret er, jo højere oppe i menuen vises det.
• aliases: Gamle URL’er, hvor denne artikel tidligere har været placeret. Hugo bruger dette til at omdirigere til denne side for at undgå 404-fejl. Hvis du nogensinde ændrer mappenavnet på en artikel, skal du tilføje dens tidligere URL som et alias her. Men generelt, ændre ikke mappenavne. Brug title i stedet.

Markdown #

Et fantastisk markup-sprog, der giver dig mulighed for at fokusere helt på indholdet, i stedet for også at kæmpe med HTML og CSS.

Markdown-filer oversættes til HTML, som derefter vises for kunden.

Det er super intuitivt at bruge. Hvis du nogensinde har brug for en huskeseddel, kan du tjekke den officielle side.

Nedenfor er de mest almindelige syntaksregler, du har brug for.

Overskrifter #

Kan tilføjes ved at bruge et antal # efterfulgt af overskriftsteksten.

Antallet af hashtags bestemmer overskriften:

h2: ## Shortcodes
h3: ### Deres syntakser
h4: #### En specifik syntaks

Afsnit #

Enhver tekst på samme eller den følgende linje vises som et enkelt afsnit. At tilføje 1 linje plads mellem linjer adskiller afsnit:

Al tekst her er et afsnit.
Selv teksten her vil være på samme linje som den ovenfor.

Tekst, der vises her, får sit eget afsnit.

Links & Ankre #

Kan tilføjes ved simpelthen at fremhæve den tekst, du vil oprette et link til, og indpakke det i parenteser efterfulgt af en parentes med linket

... læs mere om [Indhold her](/platform/content/settings/)

Når du henviser til artikler i Knowledge Centeret, skal du kun inkludere den relative sti som i eksemplet. For eksterne referencer skal du inkludere den fulde URL.

Du kan bruge ankre til at sende læsere til specifikke dele af længere artikler ved at bruge # efterfulgt af en overskrifts ID i referencen.

ID’et er en sanitiseret version af navnet. F.eks. vil overskriften “For udviklere” få ID’et for-developers.

Dette kan bruges til at henvise til overskrifter inden for artiklen selv eller til at henvise til andre artikler ved også at inkludere deres relative sti:

Tjek [For udviklere](#for-developers) sektionen længere nede.

Tjek [Almindelige synkroniseringsfejl for Magento2 her](/integrations/magento-2/faq/#common-sync-issues).

Billeder #

Vi bruger en tilpasset shortcode til at vise screenshots i artikler.

Du bør altid outputte billeder som .webp fra Brandbird for at holde kvaliteten høj og filstørrelsen lav.

Billeder gemmes i den samme mappe, hvor din _index.md er, for at holde dem organiseret med artiklen.

Shortcode syntaksen er:

{{< image "IMAGE_ALT" "FILENAME.webp" >}}

Skriv altid en alt-tekst for billedet, så søgemaskiner kan forstå, hvad der vises på dem.

UI-referencer #

Knowledge Centeret oversættes automatisk, så for at undgå at oversætte menupunkter bruger vi en specifik shortcode til at henvise til vores brugergrænseflade.

Syntaksen er:

{{< uiref "Search > Designs > New Design > Omnisearch" >}}

Hvis du har brug for at tilføje en UI-reference i en overskrift, er syntaksen lidt anderledes, fordi Hugo gengiver overskrifter på en anden måde end resten af teksten:

{{% uiref "Search > Designs > New Design > Omnisearch" %}}

Outputtet af dette vil vise sig som fed tekst, der forbliver den samme på tværs af oversættelser: Search > Designs > New Design > Omnisearch

Callouts #

Disse er farvede bokse, der kan bruges til at fremhæve vigtige punkter. De bør bruges sparsommelig, og kun når noget er særligt vigtigt.

Det betyder også, at enhver enkelt artikel generelt ikke bør indeholde mere end 1 af hver af disse, da de ellers komplicerer artiklen.

Syntaksen er:

{{< hint info|warning|danger >}}
**Noget**: At være opmærksom på.
{{< /hint >}}

Der er tre typer af callouts:

Info om noget, der er godt at vide, som vores forslag til en startskabelon.

Advarsel om noget, der kunne blive et problem, som at glemme at gemme, før man forlader en side.

Fare om noget, der kunne bryde en hel opsætning, som at opgradere en udvidelse uden først at lave en backup.

Brug dem kun, når det virkelig er nødvendigt, og i henhold til alvorligheden af, hvad de forklarer.

Kodeblokke #

Disse kommer i to variationer - inline og blok.

En inline kodeblok, der oprettes ved hjælp af to backticks `sådan her`.

Fulde kodeblokke oprettes ved at indpakke koden med 3 backticks i starten og slutningen og tilføje kodens sprog for syntaks:

console.log("Hvilket et fantastisk kodeeksempel!");

Begynd at skrive #

Nu er du klar til at begynde at skrive indhold i verdensklasse!

Der er meget at fordøje i denne artikel, og du vil sandsynligvis ikke huske halvdelen af det i morgen. Tag en pause, spis noget, og læs det igen.

Find derefter en artikel i Knowledge Centeret, som du mener kunne være bedre, og omskriv den ved hjælp af disse retningslinjer. Hold denne guide åben, når du skriver, så du kan referere til den.

Når du har gjort dit bedste, skal du søge feedback fra en kollega - det behøver ikke tage mere end 10 minutter, og de vil være i stand til at spotte aspekter, du måske ikke har bemærket.

Alle får tunnelvision, når de skriver, så feedback er afgørende for at skrive det bedst mulige indhold.

God skriven!