diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 099ef6b03509b..ecf19e4ff8faf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -30,6 +30,8 @@ If you are already familiar with Julia itself, this blog post by Katharine Hyatt
 
 * Review discussions on the [Julia Discourse forum](https://discourse.julialang.org).
 
+* Review [Writing Documentation](https://github.com/JuliaLang/julia/blob/master/doc/src/manual/documentation.md#writing-documentation).
+
 * For more detailed tips, read the [submission guide](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md#submitting-contributions) below.
 
 * Relax and have fun!
@@ -181,6 +183,15 @@ At the moment, this should always be done with the following `compat` admonition
       This method was added in Julia 1.X.
   ```
 
+#### Documenting unstable APIs
+
+Some contributions are intended primarily for internal use or may be part of an API that is still in development. In addition to appropriate documentation, relevant code should be clearly annotated as unstable as follows:
+
+  ```
+  !!! danger "Unstable"
+      This method is unstable and subject to change without notice.
+  ```
+
 ### Contributing to core functionality or base libraries
 
 *By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).*