Ilmoitukset (huomautukset, muistiinpanot, varoitukset jne.), Ilmoitukset (huomautukset, huomautukset, varoitukset jne.)

DevSite tukee useita ilmoitustyylejä, jotka esitetään laatikoina eri taustaväreillä. Taustavärit ovat ennalta määritettyjä, ja voit luoda ilmoituksia joko HTML:n tai Markdownin avulla.

Saatavilla olevat ilmoitustyypit

Huom

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

Note: An ordinary note.

Kärki

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

Tip: An ordinary tip.

Varoitus

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

Caution: Suggests proceeding with caution.

Varoitus

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

Tärkeää

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

Important: Defines an important concept.

Avainkohta

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

Key Point: Defines an important takeaway.

Avaintermi

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

Key Term: Defines important terminology.

Tavoite

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

Objective: Defines the goal of a procedure.

Menestys

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

Beeta

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

Esikatselu

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

Käytöstä poistettu

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

Käyttöohjeita

HTML:n käyttö

Suosittelemme käyttämään näitä luokkia HTML5 <aside> -elementin kanssa, mutta voit käyttää sen sijaan toista lohkotason elementtiä (kuten <p> ).

HTML-luokat määrittävät ilmoituksen värin ja kuvakkeen, mutta ne eivät aseta automaattisesti lihavoitua ensimmäistä sanaa. sinun on kirjoitettava tämä sana käsin esimerkeissä esitetyllä tavalla. Voit teoriassa käyttää jotain muuta kuin luokkaa vastaavaa sanaa, mutta suosittelemme, että pidät yllä ensimmäisistä sanoista.

Vanhemmissa asiakirjoissa saatat nähdä class="special" tai ei-standardiluokan nimiä class="note" sijasta. Nämä luokkien nimet tuottavat huomautuksia, jotka ovat visuaalisesti identtisiä note kanssa, mutta suosittelemme käyttämään class="note" erityisten tai epästandardien luokkanimien sijaan.

Markdownin käyttö

Markdown-tyylit määrittävät ilmoituksen värin ja kuvakkeen, ja ne asettavat automaattisesti ilmoituksen lihavoitun ensimmäisen sanan. Joten esimerkiksi huomautus Markdownissa alkaa aina sanalla Note: lihavoituna.

Jos ilmoituksessa on useampi kuin yksi kappale, käytä sen sijaan HTML-koodia <aside> (ja <p> ).

Saatat nähdä Tärkeää: sen sijaan, että Note: . Tämä Markdown-tyyli tuottaa ilmoituksia, jotka ovat visuaalisesti identtisiä Note: -ilmoituksen kanssa.

Parhaat käytännöt

DevSite suosittelee, että noudatat seuraavia parhaita käytäntöjä, kun lisäät ilmoituksia dokumentaatioon:

Suositeltava

• Ole ytimekäs (yritä pitää yhden tai kahden lauseen huomautukset).
• Rajoita ilmoitukset yhteen sivua kohden, jos mahdollista (tai yhteen osiota kohden tarvittaessa).
• Varmista, että ilmoitukset sisältävät vain tärkeää sisältöä, jonka haluat korostaa. älä sisällytä ilmoitukseen sisältöä, jonka kanssa et vain ole varma mitä tehdä.
• Käytä huomautuksia ennen kuin käyttäjä tarvitsee tietoja, älä sen jälkeen.

Ei suositella

• Älä sisällytä ilmoituksiin koodiesimerkkejä, taulukoita tai kuvia.
• Vältä ilmoitusten pinoamista päällekkäin, vaikka ne olisivatkin erityyppisiä.
• Yritä olla lisäämättä huomautuksia välittömästi otsikoiden jälkeen.
• Älä käytä ilmoituksia määrittääksesi edellytyksiä ennen toimenpidettä.

Nämä parhaat käytännöt koskevat suurimmaksi osaksi note , caution ja warning , mutta ne voivat koskea myös muita tyyppejä.

Hyviä esimerkkejä

Pidä se yksinkertaisena:

Ole cautions tietojen mahdollisen menettämisen varalta:

Käytä warning mahdollisen loukkaantumisen varalta:

Käytä asianmukaisia ​​ilmoitustyyppejä sisällössä, kuten key-term tai success :

Huonoja esimerkkejä

Ilmoitukset eivät saa olla liian monisanaisia ​​tai välittää ydinsisältöön kuuluvaa tietoa:

Ilmoituksissa ei saa määrittää edellytyksiä ennen toimenpidettä (käytä sen sijaan "Edellytykset" -osiota):