Videnscenter

Sådan skriver du gode artikler

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

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 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 hundredevis, hvis ikke tusindvis af gange, så du skal være besat af kvaliteten.

Skrivestil #

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

Jo og nej. Mest nej faktisk.

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

Tænk for eksempel på hovedårsagerne til, at Apple er en af verdens førende elektronikvirksomheder. De laver bare telefoner og laptops, ikke?

Jo, men de laver dem også i en super skarp og konsekvent 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.

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

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

Voice & 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 sikrer, at hvert nødvendigt trin er forklaret.

Vi skriver til både tekniske og ikke-tekniske læsere, så vores artikler skal være simple, men informative for begge typer læsere. Det gør vi gennem god copywriting og en klar struktur.

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

Hold det simpelt: Brug klart og letforståeligt sprog. Undgå lange, forvirrende sætninger og indviklede ord. Brug aktiv form, så teksten er direkte og let at læse.
Vær respektfuld: Skriv på en måde, der behandler læseren som en ligestillet. Antag ikke, at de allerede ved tingene. Sørg for at give alle de nødvendige oplysninger med links til mere info, hvis nødvendigt.
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 måske vil søge efter, så de let kan finde svarene.
Brug humor med omtanke: Humor er godt, hvis det falder naturligt ind, men det bør aldrig virke påtaget. Hvis du er i tvivl, så undlad. 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 det mindset, 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 virker, er de sandsynligvis i et opdagelses-mindset, og humor kan fungere godt.

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

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

Typer af artikler #

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

Informativ #

Forklarer koncepterne for et produkt eller en funktion. Læsere er som regel i opdagelsestilstand, når de læser disse, og vil forstå, hvordan det virker. Disse artikler inkluderer ikke trin eller grundig vejledning 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 vejledning, der forklarer de præcise knapper, brugerne skal klikke på, og konfigurationer de skal igennem. Læsere prøver som regel at opnå noget specifikt, når de læser disse.

Eksempler:

FAQs / Troubleshooting #

Forklarer de mest sandsynlige løsninger på almindelige spørgsmål eller problemer. Læsere er ofte frustrerede i et vist omfang, når de kigger på disse, fordi noget ikke virker som forventet. De skal være tydeligt markeret med det spørgsmål, læseren har i tankerne, og give klare forklaringer på, hvordan det løses.

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

Eksempler:

Intros #

Bemærk, hvordan denne artikel og sektionen om Skrivestil starter med en kort 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 afgøre, om de har fundet det rette indhold eller ej.

Intros bør ikke være for lange, men de skal give læseren konteksten for det, de skal til at læse.

Inkludér altid intros i starten 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 præcis. En god titel indeholder maksimalt 3 ord, og helst kun 1.

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

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

Artiklenes beskrivelser skal være én sætning, der tilføjer kontekst til artiklen. Det hjælper læserne med at afgøre, om denne artikel er det, de ledte efter. Undgå at gentage titlen i beskrivelsen – den skal supplerer den.

En god beskrivelse for Omnisearch er: “Et enkelt fuldsides vindue, der serverer dine besøgende de resultater, der mest sandsynligt vil konvertere”. Den uddyber tydeligt, hvad Omnisearch er, i en enkelt 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 står klart fra menuen i Knowledge Center.

Overskrifter #

Disse er afgørende for at gøre artikler nemme at skimme og navigere. Brug dem til tydeligt at adskille forskellige dele. Overskrifter er maksimalt 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’ere og h3’ere bruges automatisk til at oprette indholdsfortegnelsen.

Afsnit #

Når vi skriver artikler, vil vi gerne have, at læserne nemt kan navigere og forstå dem. De læser sjældent hele artiklen, men skimmer 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, skal du sikre, at teksten er let at skimme ved at tilføje linjeskift mindst efter hver 3. linje (set 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 tekstblokke og antage, at de er svære at læse, selv om de ikke er det.

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

Når vi skriver artikler, vil vi gerne have, at læserne nemt kan navigere og forstå dem. De læser sjældent hele artiklen, men skimmer 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, skal du sikre, at teksten er let at skimme ved at tilføje linjeskift mindst efter hver 3. linje (set 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 tekstblokke og antage, at de er svære at læse, selv om de ikke er det. For at visualisere forskellen, se sektionen ovenfor, hvor linjeskiftene er tilføjet. Nemere at læse, ikke?

Links #

Når det giver mening, bør du inkludere links til andre dele af Knowledge Center. Husk, at brugeren skal have alt, hvad de har brug for i én artikel, så det kan ofte betale sig mindst 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 et nyt Element. Det kan du gøre fra Recommendations > Elements > Create New. Læs mere om Elements her.

Skærmbilleder #

Vi bruger Brandbird til at lave lækre screenshots. Tilføj altid en god kontrastbaggrund til dit screenshot, som ikke stjæler opmærksomheden, men supplerer det.

Skærmbilleder 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. Copywriting-delen klarer 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 anvender god copywriting til at supplere dem.

Et screenshot bør som regel dække hele omfanget af en side, efterfulgt af tekst, der forklarer de trin, man skal tage, eller funktionerne på siden.

Fx i stedet for at vise 3 forskellige billeder for HTML, CSS og Sub-Designs hver for sig, er et enkelt billede, der viser det hele i indledningen, bedre. Anmærkninger er også velkomne for at hjælpe med at tydeliggøre dele af et billede.

Videoer #

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

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

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

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

Menuer #

Vi organiserer Knowledge Center logisk, og generelt i 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 edge-cases bør tilføjes under FAQ for det relevante emne.

Eksempler:

Artikler, der forklarer, hvordan Omnisearch virker, er relevante for alle kunder, der bruger produktet, så det har sin egen artikel.
Fejlsøgning på, hvorfor trackede ordrer ikke vises i dashboardet, er en edge-case, og sættes ind under 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 fra Markdown. Det lader os 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 i rodmappen eller i Github repoen.

Mapper & filer #

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

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

Filtræet ligner meget menustrukturen, fordi Hugo render menuen baseret på mappestrukturen, som du ser nedenfor.

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

Som standard bliver titlen på en artikel defineret af mappenavnet, så vælg dette omhyggeligt og følg de eksisterende eksempler. Titlen kan overskrives i front matter af 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 mappestrukturen 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, fx titler, beskrivelser, aliases (omdirigeringer), kategorier m.m.

Front matter placeres altid i toppen af en artikel:

---
title: "Holy Grail"
onPageTitle: "How to find the Holy Grail"
description: "Monty Pythons bedste film til dato"
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 denne ikke er inkluderet, bruges det title-cased mappenavn.
onPageTitle: En titel, der kun vises på artikelsiden, ikke i menuen. God til SEO, hvor sidetitlen fx kan være “How Product Logics Work”, mens artiklen stadig står som “Logics” i menuen.
description: Vises lige under titlen på artikelsiden. Dette er påkrævet, da det giver værdifuld kontekst for læseren.
weight: Artikelns position i menuen. Jo lavere tallet er, desto højere vises den i menuen.
aliases: Gamle URL’er artiklen tidligere har været placeret på. Hugo bruger dette til at omdirigere til siden og undgå 404-fejl. Hvis du ændrer mappenavnet på en artikel, skal du tilføje dens gamle URL som alias her. Men generelt, ændr ikke mappenavne. Brug title i stedet.

Markdown #

Et fantastisk markup-sprog, der lader dig fokusere helt på indholdet, i stedet for også at slås med HTML og CSS.

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

Det er super intuitivt at bruge. Hvis du har brug for et quick reference, så tjek den officielle side.

Nedenfor er de mest almindelige syntaksregler, du får brug for.

Overskrifter #

Oprettes ved at bruge et antal # efterfulgt af overskriftens tekst.

Antallet af hashtags afgør overskriften:

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

Afsnit #

Al tekst på samme eller næste linje vises som ét afsnit. En linjes mellemrum adskiller afsnit:

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

Tekst vist her får sit eget afsnit.

Links & Anchors #

Links oprettes ved at fremhæve teksten, du vil gøre til et link, og omslutte den med klammer efterfulgt af en parentes med linket

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

Ved reference af artikler i Knowledge Center skal du kun skrive relativ sti som i eksemplet. For eksterne referencer, brug hele URL’en.

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

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

Dette kan bruges til at referere til overskrifter internt i artiklen, eller til at referere 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 her](/integrations/magento-2/faq/#common-sync-issues).

Billeder #

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

Du bør altid bruge billeder som .webp fra Brandbird for at holde høj kvalitet og lav filstørrelse.

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

Shortcode-syntaksen er:

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

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

Automatiske baggrunde #

Billeder får automatisk en dekorativ baggrund. Dette skaber en svævende effekt med en subtil skygge, så screenshots ser mere indbydende ud.

Hvis et billede allerede har baggrund integreret (fx fra Brandbird), kan du slå automatisk 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 inkluderer egen baggrund eller kant.

UI-referencer #

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

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 renderer overskrifter på en anden måde end resten af teksten:

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

Outputtet vises som fed skrift, der forbliver ens 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 sparsomt og kun, når noget er særligt vigtigt.

Det betyder også, at en enkelt artikel generelt ikke bør indeholde mere end én af hver type, da det ellers komplicerer artiklen unødigt.

Syntaksen er:

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

Der er tre typer callouts:

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

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

Fare om noget, der kan ødelægge en hel opsætning, fx at opgradere en udvidelse uden først at tage backup.

Brug dem kun, når det virkelig er nødvendigt, og i forhold til alvoren af det de forklarer.

Kodeblokke #

Disse findes i to varianter – inline og blok.

En inline code block, der laves med to backticks `som dette`.

Fuld kodeblok 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 begynde at skrive indhold i verdensklasse!

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

Find derefter en artikel i Knowledge Center, som du mener kan blive bedre, og omskriv den efter disse retningslinjer. Hav denne guide åben, mens du skriver, så du kan slå op i den.

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 vil kunne se aspekter, du måske ikke har lagt mærke til.

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

God skrivelyst!

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