update CONTRIBUTING documentation now that you cannot really edit the…

… documentation robustly through the web interface

CONTRIBUTING.md

@@ -70,21 +70,7 @@ Coveralls shows functionality that still needs "proof of concept" tests. These a
 
 *By contributing documentation to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).*
 
-Julia's documentation is stored in the `doc` directory, and like everything else can be modified using `git`. However, for small changes one can also use GitHub's web interface:
-
-- Navigate to https://github.com/JuliaLang/julia
-- Click `doc`
-- If you want to modify an entry in the help for Julia's standard library, click `stdlib`
-- Pick the file you want to edit (for example, `base.rst`)
-- Select the `master` branch (if not browsing it already)
-- Click "Edit"
-- Click on the icon that looks like a fullscreen symbol ("Zen" mode)
-- Search for the function you want to change
-- Make your changes
-- Exit Zen mode
-- Provide a title
-- Provide a longer description of your change with the tag `[av skip]` included at the bottom (this is used in order to prevent the AppVeyor job queue from growing too large because of documentation edits)
-- Submit your change
+Julia's documentation is stored in the `doc` directory, and like everything else can be modified using `git`.
 
 Julia's documentation is built with [Sphinx](http:https://sphinx-doc.org/contents.html), which supports (and Julia's docs rely heavily on) [ReST directives](http:https://docutils.sourceforge.net/docs/ref/rst/directives.html). To build the documentation locally, run
 
@@ -96,6 +82,20 @@ or
 
 from Julia's root directory. Sometimes errors only show up in one of them, so if you're preparing a pull request it is nice if you've checked both formats before you submit.
 
+Existing docstrings now live primarily in `base/docs/helpdb.jl`.
+It is a goal over time to move the docstrings inline to their respective method defintions.
+If you want to edit the body of a method docstring, you simply then need to run the `doc/genstdlib.jl` script to regenerate the restructured text files **after** you have already rebuilt Julia.
+If you want to edit an existing docstring signature, you **first* have to change the signature in the `doc/stdlib` `..function` or `..data` defnition (not the autogenerated content) and *then*
+edit the helpdb.jl or inline method docstrings. The existing signatures in the `doc/stdlib/*.rst` files are patterned matched to base docstrings and the new content overwrites the content in `doc/stdlib/`.
+The signature definitions **must** be in sync or else the pattern match will fail and documentation will be lost in the result.
+To add entirely new methods to the `stdlib` documentation, first add the signature in the appropriate `rst/stdlib/*.rst` file before writing the docstring, rebuilding Julia, and re-running `doc/genstdlib.jl`.
+
+It is encouraged to write all new docstrings in Markdown markup.
+If you need to write a more complicated docstring that contains cross-references or citations it can be written in a restructured text (RST) codeblock.
+Many of the existing docstrings are currently restructured text codeblocks and these will be transitioned to Markdown over time.
+RST codeblocks are deliniated with the triple-quote ` ```rst ` Makdown codeblock syntax.
+The content of the codeblock is spliced directly into the final restructured text document unmodified.
+
 ### 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).*