Videnscenter

Sådan skriver du gode artikler

Giv dine kolleger mulighed for at udføre deres bedste arbejde med dokumentation i verdensklasse.
Top banner

At skrive om Clerks produkter og funktioner er en afgørende del af at gøre folk succesfulde. Vores kolleger er afhængige af Knowledge Center for al den information, de har brug for om vores produkter, når de taler med potentielle kunder, kunder og partnere.

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

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

Skrivestil #

Hvor svært kan det være at skrive dokumentation? Du nedskriver 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å hovedårsagerne til, at Apple er et af verdens førende elektronikvirksomheder. De laver bare telefoner og laptops, ikke?

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

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

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

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 nyttig information uden at forvirre dem. Vi undgår kompliceret sprog og sørger for, at hvert nødvendigt skridt 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. Det gør vi gennem god copy og en klar struktur.

Humor er velkommen, men kun hvis det passer naturligt ind. 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 aktivt sprog for at gøre teksten direkte og let 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 detaljer, de har brug for, med links til mere info, hvis nødvendigt.

  3. Vær klar og hjælpsom: Fokuser på at give nyttig information i stedet for lange forklaringer. Guid læserne trin-for-trin, og tænk over, hvad de kunne søge efter, så de let kan finde svarene.

  4. Brug humor med omtanke: Humor er fantastisk, hvis det passer naturligt ind, men det skal aldrig være tvunget. Hvis du er i tvivl om, det virker, så lad det være. 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 Search fungerer, er de sandsynligvis i en opdagelsessindstilstand, og humor kan fungere godt.

Men hvis de gennemser FAQs eller fejlsøgningsartikler, er de sandsynligvis allerede irriterede over et problem og har bare 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 geek-kulturfænomener. Det fungerer ofte rigtig godt i kodeeksempler, som du vil se ;)

Typer af artikler #

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

Information #

Forklarer koncepterne for et produkt eller en funktion. Læsere er normalt i opdagelses-mode, når de læser disse, og vil gerne forstå, hvordan det fungerer. Disse artikler indeholder ikke trin-for-trin-guides gennem backend, men forklarer tydeligt, hvordan hver del fungerer.

Eksempler:

How-Tos #

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

Eksempler:

FAQs / Fejlsøgning #

Forklarer de mest sandsynlige løsninger på almindelige spørgsmål eller problemer. Læsere er ofte frustrerede i en vis grad, når de gennemgår disse, fordi noget ikke virker som forventet. Disse bør være tydeligt mærket 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:

Intros #

Bemærk hvordan denne artikel og skrivestilssektionerne starter med et 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æseren kontekst for det, de skal til at læse.

Inkludér altid intros i begyndelsen af artikler, og når du starter nye sektioner med en h2-overskrift.

Titel & Beskrivelse #

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

En god titel er “Omnisearch”. En dårlig version er “Our Omnisearch Feature”. 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 Center let at navigere.

Artiklens beskrivelse bør være en enkelt sætning, der tilføjer kontekst til artiklen. Det hjælper læseren med at validere, om dette er artiklen, de ledte efter. Undgå at gentage titlen i din beskrivelse – den skal supplere den.

En god beskrivelse af Omnisearch er: “Et enkelt fuldsidevindue, der præsenterer dine besøgende for de resultater, der mest sandsynligt konverterer.” Det uddyber klart, hvad Omnisearch er, i en enkelt sætning.

En dårlig er: “Omnisearch er en ny funktion i vores search produkt”. Den gentager navnet på funktionen og dens placering i vores katalog, hvilket allerede fremgår af Knowledge Center-menuen.

Overskrifter #

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

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

  • h1: Kun brugt 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 du skriver artikler, ønsker vi, at læserne let kan navigere og forstå dem. Ofte læser de ikke hele artiklen, men skimter igennem 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 tekstmure. Når du skriver, så sørg for, at det er let at skimme ved at tilføje linjeskift efter mindst hver 3. linje (når det ses på en 13-tommer laptop).

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

For at visualisere forskellen, se afsnittet nedenfor, hvor linjeskift er fjernet. Sværere at skimme, ikke?


Når du skriver artikler, ønsker vi, at læserne let kan navigere og forstå dem. Ofte læser de ikke hele artiklen, men skimter igennem 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 tekstmure. Når du skriver, så sørg for, at det er let at skimme ved at tilføje linjeskift efter mindst hver 3. linje (når det ses på en 13-tommer laptop). Dette er ikke et strengt krav, men en god tommelfingerregel. Vores hjerner har en tendens til at se på store blokke tekst og konkludere, at de er svære at læse, selvom de ikke er det. For at visualisere forskellen, se afsnittet ovenfor, hvor linjeskift er tilføjet. Nemmer at læse, ikke?

Hvor det giver mening, inkludér links til andre dele af Knowledge Center. Husk, at brugeren skal have alt, de behøver i én artikel, så det er ofte værd at opsummere pointerne, før du linker til en anden artikel med mere info.

Eksempel:

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

Skærmbilleder #

Vi bruger Brandbird til at lave flotte skærmbilleder. Inkludér altid en god kontrastbaggrund til dit screenshot, som ikke stjæler opmærksomhed, men komplementerer det.

Skærmbilleder er vigtige, fordi de viser læseren, at de er det rigtige sted i vores backend. Deres hovedformål er derfor at give kontekst, ikke at vise hver eneste interaktion. Teksten gør det.

Som regel bruges højst ét kontekstskærmbillede eller video i starten af en artikel. Nogle artikler har slet ikke brug for et visuelt element. Inkludér kun et billede i brødteksten, når det forklarer noget, teksten ikke kan vise så klart, fx DNS-opsætningsdiagrammet.

Se hvordan Linear bruger screenshots sparsomt og benytter god copywriting til at supplere dem.

Et screenshot skal vise nok af siden til at give læseren orientering. Følg det op med tekst, der forklarer de trin, der skal tages, eller de funktioner, der er tilgængelige.

F.eks. i stedet for at vise tre separate billeder for HTML, CSS og Sub-Designs, vis ét nyttigt overblik i starten af artiklen. Anmærkninger kan tydeliggøre et vigtigt område.

Videoer #

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

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

Hvis videoen er artikelens primære visuelle element, placér den nær toppen i stedet for at tilføje et separat kontekstskærmbillede.

Videoer skal dog aldrig erstatte tekst, så alt, hvad der vises i en video, skal også være skrevet som tekst.

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

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

Kun artikler, der gælder for alle kunder, skal have deres egne sider. Eventuelle edge-cases tilføjes under FAQ for det relevante emne.

Eksempler:

  • Artikler, der forklarer, hvordan Omnisearch fungerer, gælder for alle kunder, der bruger produktet, så det har sin egen artikel.
  • Fejlfinding på, hvorfor sporede ordrer ikke vises i dashboardet, er en edge-case og placeres i FAQ for Any (Webshop).

Hugo #

Hele vores Knowledge Center er skrevet med Hugo Themes – Et letvægts-templating-system, der genererer statiske HTML-filer fra Markdown. Det gør det muligt for os at arbejde udelukkende i /content-mappen og Hugo renderer det hele flot gennem vores tema.

Se, hvordan du kommer i gang med Hugo i README.md-filen, som findes i rodmappen eller i Github repo.

Mapper & filer #

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

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

Filtræstrukturen ligner menustrukturen, fordi Hugo renderer menuen baseret på den mappe-struktur, du ser nedenfor.

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

Som standard defineres titlen på en artikel af mappenavnet, så vælg det med omhu og følg 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 (the search page file)
│        └── writing (this article)	
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- site configuration

URL’en for hver artikel genereres ud fra mappe-strukturen ned til det sidste lag, 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 (redirects), kategorier med mere.

Front matter er altid placeret ø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, der bruges til at tilpasse dens menupunkt. Hvis den ikke er medtaget, bruges mappe-navnet i Title Case.
  • onPageTitle: En titel, der kun vises på artikel-siden, ikke i menuen. Dette er godt til SEO, hvor side-titlen kunne være “How Product Logics Work”, mens artiklen stadig vises som “Logics” i menuen.
  • description: Vises lige under titlen på artikel-siden. Dette er påkrævet, da det giver værdifuld kontekst for læseren.
  • weight: Artiklernes placering i menuen. Jo lavere tal, desto højere oppe vises den i menuen.
  • aliases: Gamle URL’er, hvor denne artikel tidligere har ligget. Hugo bruger dette til at redirecte til denne side for at undgå 404-fejl. Hvis du nogensinde ændrer mappenavnet på en artikel, skal du tilføje dens tidligere URL som alias her. Men generelt, ændr ikke mappenavnene. Brug title i stedet.

Markdown #

Et fantastisk markup-sprog, der gør, at du kan fokusere helt på indholdet i stedet for også at skulle slås med HTML og CSS.

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

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

Nedenfor finder du de mest almindelige syntax-regler, du skal bruge.

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 efterfølgende linje vises som et enkelt afsnit. Tilføjelse af én linjes mellemrum adskiller afsnit:

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

Tekst her vises som sit eget afsnit.

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

... læs mere om [Content her](/platform/elements/settings/)

Når du henviser til artikler i Knowledge Center, behøver du kun medtage relative stier, som i eksemplet. For eksterne henvisninger, medtag hele URL’en.

Du kan bruge ankre til at sende læsere til bestemte dele af længere artikler, ved at bruge # efterfulgt af headerens ID i referencen.

ID’et er en saniteret version af navnet. F.eks. vil headeren “For Developers” få ID’et for-developers.

Dette kan bruges til at linke til headers i samme artikel eller til at linke til andre artikler ved også at inkludere deres relative sti:

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

Se [Common sync errors for Magento2 her](/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 bevare høj kvalitet og lav filstørrelse.

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

Shortcode syntaksen er:

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

Skriv altid en alt-tekst til billedet, så søgemaskiner kan forstå, hvad det viser.

Automatisk baggrund #

Billeder får automatisk en dekorativ baggrund. Det skaber en flydende effekt med en subtil skygge, hvilket gør screenshots mere visuelt indbydende.

Hvis et billede allerede har en baggrund (fx fra Brandbird), kan du deaktivere den automatiske baggrund ved at tilføje "no-background" som tredje parameter:

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

Brug "no-background" når dit screenshot allerede har sin egen baggrund eller kant.

UI-referencer #

Knowledge Center oversættes automatisk, så for at undgå at oversætte menu-punkter bruger vi en bestemt shortcode til at referere til vores brugerflade.

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 vises som fed tekst, der forbliver den samme på tværs af oversættelser: Search > Designs > New Design > Omnisearch

Callouts #

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

Det betyder også, at enhver enkelt artikel generelt ikke bør indeholde mere end én af hver, da det ellers gør artiklen for kompliceret.

Syntaxen er:

{{< hint info|warning|danger >}}
**Noget**: At være opmærksom 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 kan blive et problem, f.eks. at glemme at gemme før du forlader en side.
Fare om noget, der kan ødelægge en hel opsætning, f.eks. 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 alvoren af det, de forklarer.

Kodeblokke #

Disse findes i to varianter – inline og blok.

En inline kodeblok, der laves med to bagud-accenter `som dette`.

Hele kodeblokke laves ved at omslutte koden med 3 backticks i starten og slutningen, samt tilføje kodesproget for syntax:

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

Kom i gang med at skrive #

Nu er du klar til at skrive indhold i verdensklasse!

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

Find derefter en artikel i Knowledge Center, som du mener kunne blive bedre, og omskriv den med disse retningslinjer. Hold denne guide åben, mens du skriver, så du kan referere til den.

Når du har gjort dit bedste, så find feedback hos en kollega – det behøver ikke tage mere end 10 minutter, og de kan ofte spotte ting, du måske ikke har set.

Alle får tunnelsyn, når de skriver, så feedback er afgørende for det bedste indhold.

God skrivelyst!

Denne side er oversat af en hjælpsom AI, og der kan derfor være sproglige fejl. Tak for forståelsen.