diff --git a/docs/documentation.md b/docs/documentation.md
new file mode 100644
index 0000000000000000000000000000000000000000..78169fb0b42cf8c8e018aec62d0408415c94b29b
--- /dev/null
+++ b/docs/documentation.md
@@ -0,0 +1,54 @@
+# Writing Documentation
+
+[CiviCRM.org/documentation](https://civicrm.org/documentation) has a nice high-level list of all active documentation.
+
+## Guides in mkdocs
+
+We are using [mkdocs](http://www.mkdocs.org) to produce guides, and currently have the following two:
+
+* [User Guide](https://docs.civicrm.org/user/en/stable/)
+* [Developer Guide](https://docs.civicrm.org/dev/en/master/) *(which you are reading now!)*
+
+The content for each of these guides is written in markdown, stored in text files, and hosted on GitHub.
+
+### How to edit
+
+For minor changes you can simply edit the markdown online using GitHub. However, for a better editing experience we highly recommend installing `mkdocs`:
+
+1. Obtain the source files for the guide you want to edit
+ 1. Find the repository on GitHub (e.g. here is [the repo for this guide](https://github.com/civicrm/civicrm-dev-docs))
+ 1. Fork and clone locally. (For more help with Git and GitHub see [Git](git))
+1. Install mkdocs on your machine.
+ 1. For Ubuntu
+
+ sudo apt-get install python-pip python-wheel
+ sudo pip install mkdocs
+
+ 1. For other platforms, follow instructions on [mkdocs.org](http://www.mkdocs.org)
+
+1. Launch a local copy of the guide
+ 1. Run:
+
+ cd civicrm-dev-docs
+ mkdocs serve
+
+ * If you get `[Errno 98] Address already in use` then try using a different port
+ with `mkdocs serve -a localhost:8001`
+
+ 1. Go to `http://localhost:8000` to view
+
+1. Edit the [markdown](markdownrules) with an editor of your choice. As you save your changes `mkdocs` will automatically reprocess the page and refresh your browser.
+
+1. When you are happy with your edits use git to commit and push your chnanges then submit a pull request on GitHub.
+
+
+### Formatting
+
+See [Markdown](markdownrules) for formatting syntax within mkdocs.
+
+
+## Documentation in the wiki
+
+The [CiviCRM wiki](https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation) has lots of great info but is slowly falling out of use in favor of mkdocs.
+
+
diff --git a/docs/index.md b/docs/index.md
index 17b8c66e0fb7e6cfe7ef46fa3b0c78b48a61d288..14d50dc59816e2d1278f1d3ae40209a288457a96 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,14 +1,24 @@
-<h1>About this documentation</h1>
+# About this documentation
-CiviCRM is an open-source application. The code can poked, prodded, twisted, and hacked. It can be customized, extended, and collaboratively developed. This documentation tells you how to do that.
+## Overview
-It starts with a ***guide*** - a high level introduction to get you familiar with CiviCRM development. It covers setting up your developer environment, ensuring that you really need to start coding (i.e. you can't acheive what you want thought configuration or installing an already existing extension), best practice ways to extend CiviCRM (aka how to write an extensions), things you should know before you start hacking on core, and best practice for testing.
+[CiviCRM](https://civicrm.org) is an open-source application. The code can be poked, prodded, twisted, and hacked. It can be customized, extended, and collaboratively developed. This documentation tells you how to do that.
+
+It starts with a ***guide*** - a high level introduction to get you familiar with CiviCRM development. It covers setting up your developer environment, ensuring that you really need to start coding (i.e. you can't achieve what you want thought configuration or installing an already existing extension), best practice ways to extend CiviCRM (aka how to write an extensions), things you should know before you start hacking on core, and best practice for testing.
The guide is followed by detailed ***references*** for tools and subsystems of CiviCRM. These cover topics like the API and hook system and are intended for use by people that are familiar with CiviCRM development.
-These documents are a work in progress. You may find things in the [wiki](http://wiki.civicrm.org/confluence/display/CRMDOC/Develop) that are not documented here.
+## Editing & reading offline
+
+* This documentation is made with mkdocs and [stored in GitHub](https://github.com/civicrm/civicrm-dev-docs)
+* See the "[Writing Documentation](documentation.md)" section in this guide for specific details on editing this documentation (and others using mkdocs). You can also learn how to read these docs off-line!
+
+## Caveats
+
+* These documents are a work in progress.
+* You may find things in the [wiki](http://wiki.civicrm.org/confluence/display/CRMDOC/Develop) that are not documented here.
-<h1>Other sources of information</h1>
+# Other sources of information
As an open-source project, CiviCRM is managed by an international community of developers and activists. Help from these people can be found in the following ways:
diff --git a/docs/markdownrules.md b/docs/markdownrules.md
index 18d56b8a1a80562e7ba19bb23cca7d63b3bb0ec9..8b9b0c48921531140d1244ca7ac29c3a1a4cc756 100644
--- a/docs/markdownrules.md
+++ b/docs/markdownrules.md
@@ -3,25 +3,6 @@ Overview
In order for your CiviCRM extension to be compliant, you must provide a minimal extension documentation, written in [Markdown](https://guides.github.com/features/mastering-markdown/) language.
-The allowed structure is the following:
-
-* Headings (eg. [Heading 1](#heading-1), [Heading 2](#heading-2), [Heading 3](#heading-3))
-
-* [Styling Texts](#styling-text)
-
-* [Blockquotes](#blockquotes)
-
-* [Unordered Lists](#unordered-lists)
-
-* [Ordered Lists](#ordered lists)
-
-* [Nested Lists](#nested-lists)
-
-* Inline code block (see [example](#code-inline))
-
-* [Links](#links)
-
-* Table creation - Avoid creating tables! If you still want to use them, avoid complex columns/rows
Examples
========
diff --git a/mkdocs.yml b/mkdocs.yml
index 695dfbbf98bdc4e499964df86b72624ac4304bc0..25fe2150df760a602029097efe10f6453fbbfda4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,4 +1,7 @@
site_name: CiviCRM Developer Documentation
+repo_url: https://github.com/civicrm/civicrm-dev-docs
+site_description: 'A guide for CiviCRM developers.'
+site_author: 'The CiviCRM community'
theme: readthedocs
pages:
- Home: index.md
@@ -10,6 +13,7 @@ pages:
- Develop: develop.md
- Git: git.md
- Testing: testing.md
+ - Writing Documentation: documentation.md
- 'Reference: APIv3':
- General: api/general.md
- 'Usage': api/usage.md