Paziņojumi (norādes, piezīmes, brīdinājumi utt.), Paziņojumi (norādes, piezīmes, brīdinājumi utt.)

DevSite atbalsta vairākus paziņojumu stilus, kas tiek parādīti kā lodziņi ar dažādām fona krāsām. Fona krāsas ir iepriekš noteiktas, un jūs varat izveidot paziņojumus, izmantojot HTML vai Markdown.

Pieejamie paziņojumu veidi

Piezīme

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

Note: An ordinary note.

Padoms

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

Tip: An ordinary tip.

Uzmanību

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

Caution: Suggests proceeding with caution.

Brīdinājums

<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."

Svarīgi

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

Important: Defines an important concept.

Galvenais punkts

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

Key Point: Defines an important takeaway.

Galvenais termins

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

Key Term: Defines important terminology.

Mērķis

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

Objective: Defines the goal of a procedure.

Panākumi

<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.

Priekšskatījums

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

Preview: A note or tip for a feature preview.

Izstrādes programmatūra

<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.

Novecojis

<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.

Lietošanas piezīmes

HTML lietojums

Mēs iesakām izmantot šīs klases ar HTML5 elementu <aside> , taču tā vietā varat izmantot citu bloka līmeņa elementu (piemēram, <p> ).

HTML klases nosaka paziņojuma krāsu un ikonu, taču tās automātiski neiestata pirmo vārdu treknrakstā; šis vārds ir jāraksta manuāli, kā parādīts piemēros. Teorētiski jūs varētu izmantot vārdu, kas nav klasei atbilstošs, taču mēs iesakām pieturēties pie pirmajiem iepriekš norādītajiem vārdiem.

Vecākos dokumentos var tikt rādīti class="special" vai nestandarta klašu nosaukumi class="note" vietā. Šie klašu nosaukumi rada paziņojumus, kas ir vizuāli identiski note paziņojumam, taču mēs iesakām izmantot class="note" nevis īpašus vai nestandarta klašu nosaukumus.

Atzīmes izmantošana

Markdown stili nosaka paziņojuma krāsu un ikonu, un tie automātiski iestata paziņojuma pirmo vārdu treknrakstā. Piemēram, piezīme pakalpojumā Markdown vienmēr sākas ar vārdu Piezīme: treknrakstā.

Lai paziņojumam ir vairāk nekā viena rindkopa, izmantojiet HTML <aside> (un <p> ).

Note: . Šis Markdown stils rada paziņojumus, kas ir vizuāli identiski Note: paziņojumam.

Labākā prakse

DevSite iesaka ievērot tālāk norādīto paraugpraksi, pievienojot dokumentācijai paziņojumus.

Ieteicams

• Esiet kodolīgs (mēģiniet ievērot vienu vai divus teikumus).
• Ja iespējams, ierobežojiet paziņojumus līdz vienam lapā (vai vienu katrā sadaļā, ja nepieciešams).
• Pārliecinieties, ka paziņojumos ir ietverts tikai svarīgs saturs, ko vēlaties izcelt; neiekļaujiet paziņojumā saturu, ar kuru jūs vienkārši nezināt, ko darīt.
• Izmantojiet paziņojumus, pirms lietotājam nepieciešama informācija, nevis pēc tam.

Nav ieteicams

• Paziņojumos neiekļaujiet kodu piemērus, tabulas vai attēlus.
• Izvairieties no paziņojumu salikšanas vienu virs otra, pat ja tie ir dažāda veida.
• Centieties neiekļaut paziņojumus uzreiz aiz virsrakstiem.
• Neizmantojiet paziņojumus, lai norādītu priekšnosacījumus pirms procedūras.

Lielākoties šī paraugprakse attiecas uz paziņojumiem, kuru veids ir note , caution un warning , taču tā var attiekties arī uz citiem veidiem.

Labi piemēri

Esiet vienkārši:

Ievērojiet cautions iespējamu datu zudumu gadījumā:

Izmantojiet warning par iespējamiem savainojumiem:

Saturam izmantojiet atbilstošus paziņojumu veidus, piemēram, key-term vai success :

Slikti piemēri

Paziņojumi nedrīkst būt pārāk detalizēti, un tajos nedrīkst būt informācija, kas ietilpst galvenajā saturā.

Paziņojumos pirms procedūras nav jānorāda priekšnosacījumi (tā vietā izmantojiet sadaļu "Priekšnoteikumi"):