Merge pull request #308 from jodh-intel/mention-warnings

docs: Add warnings to doc requirements doc

Documentation-Requirements.md

@@ -1,6 +1,7 @@
 * [Introduction](#introduction)
 * [General requirements](#general-requirements)
 * [Notes](#notes)
+* [Warnings and other admonitions](#warnings-and-other-admonitions)
 * [Files and command names](#files-and-command-names)
 * [Code blocks](#code-blocks)
 * [Images](#images)
@@ -18,7 +19,7 @@ Containers](https://github.com/kata-containers) project.
 # Notes
 
 Important information that is not part of the main document flow should be
-added as a Note in bold with all content contained within block quote:
+added as a Note in bold with all content contained within a block quote:
 
 > **Note:** This is areally important point!
 >
@@ -35,6 +36,24 @@ If there are multiple notes, bullets should be used:
 >
 > - I am important point *n*.
 
+# Warnings and other admonitions
+
+Use the same approach as for [notes](#notes). For example:
+
+> **Warning:** Running this command assumes you understand the risks of doing so.
+
+Other examples:
+
+> **Warnings:**
+>
+> - Do not unplug your computer!
+> - Always read the label.
+> - Do not pass go. Do not collect $200.
+
+> **Tip:** Read the manual page for further information on available options.
+
+> **Hint:** Look behind you!
+
 # Files and command names
 
 All filenames and command names should be rendered in a fixed-format font
@@ -72,7 +91,7 @@ utility.
       ```bash
       $ echo "Hi - I am some bash code"
       $ sudo docker run -ti busybox true
-      $ [ $? -eq 0 ] && echo "success!"
+      $ [ $? -eq 0 ] && echo "success"
       ```
 
   ```