Merge pull request #16 from seanmadsen/master

Documentation about the documentation 

docs/documentation.md

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

docs/index.md

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

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

mkdocs.yml

 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