Sådan skriver du gode artikler

Det er vores hellige pligt (svag englekor) at gøre det nemt at navigere og sørge for, at hver artikel er supergodt 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 hundredvis, hvis ikke tusindvis af gange, så du skal være besat af kvaliteten.

Skrive­stil #

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

Tja, både ja og nej. Mest nej, faktisk.

Hvordan vi skriver dokumentation er lige så afgørende som hvad vi skriver. Det er i bund og grund UX’en af vores arbejde.

Tænk på de vigtigste grunde til, at Apple er et af verdens førende elektronikfirmaer. De laver bare telefoner og laptops, ikke?

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

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

Den skal altid være konsekvent fantastisk, for at kollegaer og kunder skal være lige så religiøst investeret i at bruge det, som vi ønsker ;)

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

Stemning & Tone #

Når vi skriver til vores kunder, fokuserer vi på at gøre tingene klare og nemme at forstå. Vores mål er at give dem brugbar information 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 god tekst og en klar struktur.

Humor er velkommen, men kun hvis det falder naturligt ind. Det vigtigste er, at vi hjælper 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 aktivt sprog for at gøre teksten direkte og nem at læse.

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

3. Vær klar og hjælpsom: Fokuser på at give brugbar information frem for lange forklaringer. Guide læserne trin-for-trin, og tænk over, hvad de måske ville søge efter, så de nemt kan finde svarene.

4. Brug humor forsigtigt: Humor er godt, hvis det falder naturligt, men det skal aldrig være tvunget. Hvis du er usikker på, om det virker, så udelad det. Hold fokus på at være hjælpsom og klar.

Vores tone er uformel med stort fokus på klarhed. Humor er opmuntret, men kun hvis det passer til den tankegang, brugeren har, når de læser det. Tænk på, hvorfor brugeren er her. Hvis en bruger læser en artikel om, hvordan Search virker, er de sandsynligvis i et opdagelses-mindset, og humor kan fungere godt.

Men hvis de gennemser FAQ’er eller fejlfinding-artikler, er de sandsynligvis allerede irriterede over et problem og har blot brug for en klar løsning. Tankegang betyder noget ;)

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

Typer af artikler #

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

Informativ #

Forklarer koncepterne ved et produkt eller en funktion. Læserne er som regel i opdagelsesmodus, når de læser disse, og vil forstå, hvordan det virker. Disse artikler indeholder ikke steps eller grundig vejledning gennem backend, men forklarer tydeligt, hvordan hver del virker.

Eksempler:

• Cookieless
• Dashboard
• Conversations

How-Tos #

Forklarer, hvordan man opnår et bestemt resultat. Disse kræver trin-for-trin vejledning, der forklarer præcis hvilke knapper brugeren skal trykke på, og hvilke konfigurationer de skal igennem. Læserne prøver som regel at opnå noget specifikt, når de læser disse.

Eksempler:

• Get Started on Shopify
• Recommendations Best Practices
• Adding a new Store

FAQs / Fejlfinding #

Forklarer de mest sandsynlige løsninger på almindelige spørgsmål eller problemer. Læserne er ofte frustrerede i en eller anden grad, når de gennemser disse, fordi noget ikke virker som forventet. Disse bør tydeligt mærkes med det spørgsmål, læseren 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 Error
• Magento 2 403 Forbidden Error

Intros #

Læg mærke til, hvordan denne artikel og Writing Style-sektionen starter med en lille intro? Lagde du mærke til, hvad de opnåede?

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 se, om de har fundet det rigtige indhold.

Intros skal ikke være for lange, men de skal give læserne konteksten til det, de skal til at læse.

Inkluder altid intros i begyndelsen af artikler, og når du starter nye sektioner med et h2-heading.

Titel & Beskrivelse #

Titlen på din artikel skal altid være klar og kortfattet. En god titel indeholder maks. 3 ord og helst kun 1.

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

Korte titler fungerer godt, fordi de er nemme at overskue, og kombineret med en logisk menustruktur holder vi Knowledge Center nemt at navigere.

Artikelbeskrivelser skal være en enkelt sætning, der tilføjer kontekst til artiklen. Det hjælper læseren med at vurdere, om denne artikel er det, de ledte efter. Undgå at gentage titlen i beskrivelsen – den skal komplementere titlen.

En god beskrivelse for Omnisearch er: “Et enkelt fuldskærmsvindue, der viser dine besøgende de resultater, der med størst sandsynlighed konverterer”. Det forklarer klart, hvad Omnisearch er, i én sætning.

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

Overskrifter #

Disse er afgørende for at gøre artikler lette at skimme og navigere. Brug dem til klart at adskille forskellige dele. Overskrifter er maks. 3 ord lange.

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

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

Vi bruger aldrig overskrifter mindre end h4.

Alle h2 og h3 bruges automatisk til at oprette indholdsfortegnelsen.

Afsnit #

Når vi skriver artikler, vil vi have, at læserne let kan navigere og forstå dem. De vil sjældent læse hele artiklen, men skimme 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 ligne tekstblokke. Når du skriver, sørg for, at det er let at skimme ved at tilføje linjeskift mindst efter hver 3. linje (når det ses på en 13-tommers laptop).

Dette er ikke et strengt krav, men en god tommelfingerregel. Vores hjerner har en tendens til at betragte store tekstblokke som svære at læse, selv hvis de ikke er det.

For at visualisere forskellen, se nedenstående sektion, hvor linjeskiftene er fjernet. Sværere at skimme, ikke?

Når vi skriver artikler, vil vi have, at læserne let kan navigere og forstå dem. De vil sjældent læse hele artiklen, men skimme 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 ligne tekstblokke. Når du skriver, sørg for, at det er let at skimme ved at tilføje linjeskift mindst efter hver 3. linje (når det ses på en 13-tommers laptop). Dette er ikke et strengt krav, men en god tommelfingerregel. Vores hjerner har en tendens til at betragte store tekstblokke som svære at læse, selv hvis de ikke er det. For at visualisere forskellen, se ovenstående sektion, hvor linjeskiftene er tilføjet. Nem­mere at læse, ikke?

Links #

Når det giver mening, så inkluder links til andre dele af Knowledge Center. Husk, at brugeren bør have alt, hvad de behøver, i én artikel, så det er ofte værd at i det mindste opsummere punkterne, før du linker til en anden artikel med mere information.

Eksempel:

Før du fortsætter, skal du sørge for at oprette et nyt Element. Du kan gøre det fra Recommendations > Elements > Create New. Læs mere om Elements her.

Screenshots #

Vi bruger Brandbird til at lave lækre screenshots. Inkluder altid en god kontrastbaggrund for dit screenshot, som ikke stjæler opmærksomheden, men komplementerer det.

Screenshots er vigtige, fordi de viser læseren, at de er det rigtige sted i vores backend. Deres hovedformål er altså at give kontekst, ikke at vise alle interaktioner. Teksten 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å ok – ofte er mindre mere, når det gælder screenshots.

Se, hvordan Linear bruger screenshots sparsomt og bruger god tekst til at komplementere dem.

Et screenshot bør som udgangspunkt dække hele omfanget af en side, efterfulgt af tekst, der forklarer trinene man skal tage, 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 ét enkelt, der viser det hele i indledningen, bedre. Anmærkninger er også velkomne for at hjælpe med at forklare 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 indsættes direkte i en artikel som dette:

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

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

Når du optager videoer, gennemgå punkterne kronologisk i samme rækkefølge som artiklen, så de er nemme at følge.

Menu­punkter #

Vi organiserer Knowledge Center logisk og generelt i samme rækkefølge, som funktioner vises i vores backend.

Kun artikler, der gælder for alle kunder, bør have deres egne sider. Eventuelle særtilfælde bør tilføjes under FAQ for det relevante område.

Eksempler:

• Artikler, der forklarer hvordan Omnisearch virker, gælder for alle kunder, der bruger produktet, så det har sin egen artikel.
• Fejlfinding på, hvorfor sporede ordrer ikke vises i dashboardet, er et særtilfælde og tilføjes i FAQ for Any (Webshop)

Hugo #

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

Se, hvordan du kommer i gang med Hugo i README.md filen i roden eller i Github repoet.

Mapper & filer #

Du arbejder i content/en-mappen og i integrations & platform-under­mapperne.

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

Mappestrukturen ligner tæt menus­trukturen, fordi Hugo genererer menuen ud fra den mapperstruktur, du ser nedenfor.

Hver artikel ligger i sin egen mappe med en _index.md-fil, som du redigerer. Underscore-tegnet skal medtages, for at Hugo forstår, at det er en landing page.

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

root/
├── archetypes/
├── assets/
├── content/
│   └── en
│        └── integrations
│            └── act-on
│                └── email-recs
│                    ├── _index.md
│                    ├── screenshot_10535...
│        └── platform
│        └── search (the search page file)
│        └── writing (this article)	
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- sitekonfiguration

URL’en for hver artikel genereres ud fra mapperstrukturen ned til det sidste niveau, hvor _index.md-filen ligger. 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 med mere.

Front matter ligger altid øverst i en artikel:

---
title: "Holy Grail"
onPageTitle: "How to find the Holy Grail"
description: "Monty Python's best movie by far"
weight: 3
aliases:
   - /old/path/to/holy-grail
   - /really/old/path/to/holy-grail
---

What is the airspeed velocity of an unladen swallow?...

Den vigtigste front matter er:

• title: En brugerdefineret titel til artiklen, bruges til at tilpasse dens menupunkt. Hvis denne ikke inkluderes, bruges mappe­navnet med stort begyndelsesbogstav.
• onPageTitle: En titel, der kun vises på artikel­siden, ikke i menuen. Dette er godt til SEO-formål, hvor sidetitlen kan være “How Product Logics Work”, mens artiklen stadig står som “Logics” i menuen.
• description: Vises lige under titlen på artikel­siden. Dette er påkrævet, da det giver værdifuld kontekst til læseren.
• weight: Artikelns placering i menuen. Jo lavere tal, jo højere oppe vises den i menuen.
• 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 for en artikel, skal du tilføje dens tidligere URL som alias her. Men generelt, ændr ikke mappenavne. Brug title i stedet.

Markdown #

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

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

Det er super intuitivt at bruge. Hvis du får brug for et snydeark, så tjek den officielle side.

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

Overskrifter #

Kan tilføjes med et antal # efterfulgt af overskriftsteksten.

Antallet af hashtags afgør overskriftsniveauet:

h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax

Afsnit #

Al tekst på samme eller følgende linje vises som ét afsnit. Tilføjer du én tom linje mellem linjerne, adskilles afsnittene:

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

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

Links & Anchors #

Kan tilføjes ved blot at fremhæve den tekst, du vil lave et link ud af, og omslutte den med hakparanteser efterfulgt af en parentes med linket

... read more about [Content here](/platform/elements/settings/)

Når du henviser til artikler i Knowledge Center, skal du kun inkludere den relative sti som i eksemplet. Ved eksterne referencer, inkluder hele URL’en.

Du kan bruge anchors til at sende læsere til specifikke dele af længere artikler, ved at bruge # efterfulgt af header-ID’et i referencen.

ID’et er en renset version af navnet. F.eks. får overskriften “For Developers” ID’et for-developers.

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

Se [For Developers](#for-developers) sektionen længere nede.

Se [Common sync errors for Magento2 here](/integrations/magento-2/faq/#common-sync-issues).

Billeder #

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

Du skal altid eksportere billeder som .webp fra Brandbird for at holde kvaliteten høj og filstørrelsen lav.

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

Shortcode-syntaksen er:

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

Skriv altid en alternativ tekst til billedet, så søgemaskiner kan forstå, hvad der vises på det.

Automatiske Baggrunde #

Billeder får automatisk en dekorativ baggrund. Dette skaber en svævende effekt med en subtil skygge og gør screenshots mere visuelt tiltalende.

Hvis et billede allerede har en baggrund indbygget (f.eks. fra Brandbird), kan du slå den automatiske baggrund fra ved at tilføje "no-background" som tredje parameter:

{{< image "IMAGE_ALT" "FILENAME.webp" "no-background" >}}

Brug "no-background", når dit screenshot allerede indeholder sin egen baggrund eller kant­markering.

UI-referencer #

Knowledge Center oversættes automatisk, så for at undgå at oversætte menupunkter bruger vi en specifik shortcode til at referere til vores bruger­interface.

Syntaksen er:

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

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

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

Outputtet af dette vises som fed tekst, der forbliver det 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 pointer. De skal bruges sparsomt og kun, når noget er særligt vigtigt.

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

Syntaksen er:

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

Der er tre typer callouts:

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

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

Fare om noget, der kan ødelægge hele opsætningen, f.eks. at opgradere en udvidelse uden først at tage backup.

Brug dem kun, når det virkelig er nødvendigt, og alt efter hvor alvorligt det er.

Kodeblokke #

Disse kommer i to varianter – inline og blok.

En inline code block, som laves med to backticks `sådan her`.

Fuldstændige kodeblokke laves ved at omslutte koden med 3 backticks i begyndelsen og slutningen og tilføje sproget for syntaks:

console.log("What an awesome code example!");

Begynd at skrive #

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

Der er meget at tage ind i denne artikel, og du kan sikkert ikke huske halvdelen i morgen. Tag en pause, spis noget, og læs den igen.

Find derefter en artikel i Knowledge Center, du mener kunne være bedre, og omskriv den med disse retningslinjer. Hold denne guide åben, når du skriver, så du kan bruge den som reference.

Når du har gjort dit bedste, så bed om feedback fra en kollega – det behøver ikke tage mere end 10 minutter, og de kan ofte se ting, du ikke selv opdager.

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

God skrivelyst!