Merknader (meldinger, notater, advarsler osv.)

DevSite støtter flere oppslagsstiler, presentert som bokser med forskjellige bakgrunnsfarger. Bakgrunnsfargene er forhåndsdefinerte, og du kan lage merknader ved å bruke enten HTML eller Markdown.

Tilgjengelige varseltyper

Note

<aside class="note">
<b>Note:</b> An ordinary note.
</aside>

Note: An ordinary note.

Tupp

<aside class="tip">
<b>Tip:</b> An ordinary tip.
</aside>

Tip: An ordinary tip.

Forsiktighet

<aside class="caution">
<b>Caution:</b> Suggests proceeding with caution.
</aside>

Caution: Suggests proceeding with caution.

Advarsel

<aside class="warning">
<b>Warning:</b> Stronger than caution; it means "Don't do this."
</aside>

Warning: Stronger than caution; it means "Don't do this."

Viktig

<aside class="special">
<b>Important:</b> Defines an important concept.
</aside>

Important: Defines an important concept.

Nøkkelpunkt

<aside class="key-point">
<b>Key Point:</b> Defines an important takeaway.
</aside>

Key Point: Defines an important takeaway.

Nøkkelbegrep

<aside class="key-term">
<b>Key Term:</b> Defines important terminology.
</aside>

Key Term: Defines important terminology.

Objektiv

<aside class="objective">
<b>Objective:</b> Defines the goal of a procedure.
</aside>

Objective: Defines the goal of a procedure.

Suksess

<aside class="success">
<b>Success:</b> Describes a successful action or an error-free status.
Used only in interactive or dynamic content; don't use in ordinary
static pages.
</aside>

Success: Describes a successful action or an error-free status. Used only
in interactive or dynamic content; don't use in ordinary static pages.

Beta

<aside class="beta">
<b>Beta:</b> A notice that describes a beta-release feature, which is
subject to change or removal in new minor versions of the product.
</aside>

Beta: A notice that describes a beta-release feature, which is subject to
change or removal in new minor versions of the product.

Forhåndsvisning

<aside class="preview">
<b>Preview:</b> A note or tip for a feature preview.
</aside>

Preview: A note or tip for a feature preview.

Dogfood

<aside class="dogfood">
<b>Dogfood:</b> A notice that applies only temporarily, during internal
dogfood testing. Remove all Dogfood notices before making a document
publicly visible.
</aside>

Dogfood: A notice that applies only temporarily, during internal dogfood
testing. Remove all Dogfood notices before making a document publicly
visible.

Avviklet

<aside class="deprecated">
<b>Deprecated:</b> A note or tip for a deprecated feature, product, or
service.
</aside>

Deprecated: A note or tip for a deprecated feature, product, or service.

Bruksnotater

HTML-bruk

Vi anbefaler å bruke disse klassene med HTML5 <aside> -elementet, men du kan bruke et annet blokknivåelement (som <p> ) i stedet.

HTML-klassene bestemmer fargen og ikonet til en merknad, men de angir ikke automatisk det første ordet med fet skrift; du må skrive det ordet manuelt, som vist i eksemplene. Du kan teoretisk sett bruke et annet ord enn det som tilsvarer klassen, men vi anbefaler at du holder deg til de første ordene vist ovenfor.

I eldre dokumenter kan du se class="special" eller ikke-standard klassenavn i stedet for class="note" . Disse klassenavnene produserer merknader som er visuelt identiske med et note , men vi anbefaler å bruke class="note" i stedet for spesielle eller ikke-standard klassenavn.

Markdown-bruk

Markdown-stilene bestemmer fargen og ikonet til et varsel, og de angir automatisk det første ordet med fet skrift i varselet. Så for eksempel starter et notat i Markdown alltid med ordet Note: i fet skrift.

For en merknad med mer enn ett avsnitt, bruk HTML <aside> (og <p> ) i stedet.

Du kan se Viktig: i stedet for Note: . Denne Markdown-stilen produserer merknader som er visuelt identiske med en Note: -notis.

Beste praksis

DevSite anbefaler at du følger følgende beste fremgangsmåter når du legger til merknader i dokumentasjonen:

Anbefalt

• Vær kortfattet (prøv å holde merknader til en eller to setninger).
• Begrens varslene til én per side hvis mulig (eller én per del om nødvendig).
• Sørg for at merknader kun inneholder viktig innhold som du vil fremheve; ikke ta med innhold i en merknad som du bare ikke er sikker på hva du skal gjøre med.
• Bruk merknader før brukeren trenger informasjonen, ikke etter.

Ikke anbefalt

• Ikke ta med kodeeksempler, tabeller eller bilder i merknader.
• Unngå å stable oppslag oppå hverandre, selv om de er av forskjellige typer.
• Prøv å ikke sette inn merknader rett etter overskrifter.
• Ikke bruk merknader til å spesifisere forutsetninger før en prosedyre.

For det meste gjelder disse beste fremgangsmåtene for merknader om note , caution og warning , men kan gjelde for andre typer.

Gode ​​eksempler

Hold det enkelt:

Vær cautions for potensielt tap av data:

Bruk warning for potensiell skade:

Bruk passende varslingstyper for innhold, for eksempel key-term eller success :

Dårlige eksempler

Merknader skal ikke være for detaljerte eller formidle informasjon som hører hjemme i kjerneinnholdet:

Merknader bør ikke spesifisere forutsetninger før en prosedyre (bruk en "Forutsetninger"-del i stedet):