„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“):