Pastabos (figūrinės išnašos, pastabos, įspėjimai ir kt.)

„DevSite“ palaiko keletą pranešimų stilių, pateiktų kaip langeliai su skirtingomis fono spalvomis. Fono spalvos yra iš anksto nustatytos, o pranešimus galite kurti naudodami HTML arba Markdown.

Galimi pranešimų tipai

Pastaba

HTML

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

Pažymėjimas

Note: An ordinary note.

Patarimas

HTML

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

Pažymėjimas

Tip: An ordinary tip.

Atsargiai

HTML

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

Pažymėjimas

Caution: Suggests proceeding with caution.

Įspėjimas

HTML

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

Pažymėjimas

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

Svarbu

HTML

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

Pažymėjimas

Important: Defines an important concept.

Pagrindinis taškas

HTML

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

Pažymėjimas

Key Point: Defines an important takeaway.

Pagrindinis terminas

HTML

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

Pažymėjimas

Key Term: Defines important terminology.

Tikslas

HTML

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

Pažymėjimas

Objective: Defines the goal of a procedure.

Sėkmės

HTML

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

Pažymėjimas

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

HTML

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

Pažymėjimas

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

Peržiūra

HTML

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

Pažymėjimas

Preview: A note or tip for a feature preview.

Negalutinė versija

HTML

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

Pažymėjimas

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

Nebenaudojama

HTML

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

Pažymėjimas

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

Naudojimo pastabos

HTML naudojimas

Rekomenduojame naudoti šias klases su HTML5 elementu <aside> , bet vietoj to galite naudoti kitą bloko lygio elementą (pvz., <p> ).

HTML klasės nustato pranešimo spalvą ir piktogramą, tačiau jos automatiškai nenustato paryškinto pirmojo žodžio; tą žodį reikia parašyti rankiniu būdu, kaip parodyta pavyzdžiuose. Teoriškai galite naudoti kitą žodį, o ne tą, kuris atitinka klasę, tačiau rekomenduojame laikytis pirmųjų aukščiau pateiktų žodžių.

Senesniuose dokumentuose vietoj class="note" galite matyti class="special" arba nestandartinius klasių pavadinimus. Tie klasių pavadinimai sukuria pranešimus, kurie vizualiai yra identiški note pranešimui, tačiau rekomenduojame naudoti class="note" vietoj specialių ar nestandartinių klasių pavadinimų.

Pažymėjimo naudojimas

Markdown stiliai nustato pranešimo spalvą ir piktogramą ir automatiškai nustato paryškintą pirmąjį pranešimo žodį. Taigi, pavyzdžiui, pastaba Markdown visada prasideda žodžiu Pastaba: paryškintu šriftu.

Jei pranešate apie daugiau nei vieną pastraipą, naudokite HTML <aside> (ir <p> ).

Vietoje Note: . Šis žymėjimo stilius sukuria pranešimus, kurie vizualiai yra identiški Note: pranešimas.

Geriausios praktikos

DevSite rekomenduoja laikytis toliau pateiktos geriausios praktikos pridedant įspėjimų į savo dokumentus:

Rekomenduojama

  • Būkite glaustas (stenkitės laikytis vieno ar dviejų sakinių).
  • Jei įmanoma, apribokite pranešimus iki vieno puslapyje (arba po vieną kiekviename skyriuje, jei reikia).
  • Įsitikinkite, kad pranešimuose yra tik svarbus turinys, kurį norite pabrėžti; neįtraukite į pranešimą turinio, kuriuo tiesiog nežinote, ką daryti.
  • Naudokite pranešimus prieš vartotojui prireikus informacijos, o ne po to.

Nerekomenduojama

  • Į pranešimus neįtraukite kodų pavyzdžių, lentelių ar vaizdų.
  • Venkite dėti užrašų vienas ant kito, net jei jie yra skirtingų tipų.
  • Stenkitės neįterpti pranešimų iškart po antraščių.
  • Nenaudokite pranešimų, kad nurodytumėte būtinas sąlygas prieš procedūrą.

Dažniausiai ši geriausia praktika taikoma pranešimams, kurių tipas yra note , caution ir warning , tačiau gali būti taikomi ir kitiems tipams.

Geri pavyzdžiai

Laikykite tai paprasta:

Būkite cautions dėl galimo duomenų praradimo:

Naudokite warning dėl galimo sužalojimo:

Turiniui naudokite tinkamus pranešimų tipus, pvz., key-term arba success :

Blogi pavyzdžiai

Pranešimai neturėtų būti pernelyg žodiniai arba juose neturėtų būti perteikiama informacija, kuri priklauso pagrindiniam turiniui:

Pranešimuose prieš procedūrą neturėtų būti nurodytos būtinosios sąlygos (vietoj to naudokite skyrių „Būtinos sąlygos“):