updates and format

docs/basics/codebase.md → docs/core/architecture.md

 # The codebase
 
-Having a general overview of the codebase and high level understanding of how
-it is organised, where to find specific types and bits of code, etc. is really
-useful when you are getting started with developing CiviCRM. This chapter looks
-at a few key parts of the codebase to give you an idea of how everything fits
-together.
+This chapter provides a general overview of the codebase organisation.
 
-Download CiviCRM from sourceforge.net unzip it and have a look around the
-codebase.  The rest of this chapter explores the directories inside the CiviCRM
-zip file.
+In order to explore the directories inside the CiviCRM repository it is
+generally quickest to to make a local clone of the CiviCRM from GitHub.
 
-## Object oriented
-The CiviCRM codebase is object oriented. If you aren't familiar with object
-oriented programming, spend a little time reading some beginner tutorials on
-the net.
+!!! tip
+    The CiviCRM codebase is object oriented. If you aren't familiar with object
+    oriented programming, spend a little time reading some beginner tutorials on
+    the net.
 
 ## Namespaces
 Classes in CiviCRM must be placed in one of two folders:
 
-Folder
-Example Class
-Description
-When to Use
-CRM	CRM_Core_Invoke
-"CRM" classes use PEAR-style class-naming conventions that were common up until
+***CRM*** (e.g.: `CRM_Core_Invoke`)
+classes use PEAR-style class-naming conventions that were common up until
 PHP 5.2. Class names include underscores and MUST NOT use the PHP
-"[namespace](http://wiki.civicrm.org/confluence/php.net/namespace)"
-directive.
-Use "CRM" when creating classes that plug into existing "CRM" subsystems – such
+"[namespace](http://php.net/namespace)"
+directive. Use "CRM" style when creating classes that plug into existing "CRM"
+subsystems such
 as payment processors (CRM_Core_Payment) and reports (CRM_Report).
-Civi	\Civi\API\Kernel
-"Civi" classes use PHP 5.3 namespaces. They MUST use the "namespace" directive.
-Namespaces are designated with "\".
-
 
-At time of writing (May 2014, before Civi 4.5), some classes may not load
-properly if they are in "Civi" – for example, the payment system will only load
-payment-processor classes in "CRM_Core_Payment". If you encounter problems like
-this, please submit an issue and/or patch.
+***Civi*** (for example `\Civi\API\Kernel`
+"Civi" classes use PHP 5.3 namespaces. They MUST use the
+"[namespace](http://php.net/namespace)" directive.
+Namespaces are designated with "\".
 
-The "Civi" namespace uses composer's PSR-0 autoloader. This autoloader does not
-support custom PHP overrides.
-Use "Civi" when creating new object-oriented subsystems (like \Civi\API).
+    !!! notice
+    At time of writing (May 2014, before Civi 4.5), some classes may not load
+    properly if they are in "Civi" – for example, the payment system will only load
+    payment-processor classes in "CRM_Core_Payment". If you encounter problems like
+    this, please submit an issue and/or patch.
 
+    !!! tip
+    The "Civi" namespace uses composer's PSR-0 autoloader. This autoloader does not
+    support custom PHP overrides.
+    Use "Civi" when creating new object-oriented subsystems (like \Civi\API).
 
 ## Business logic
-Most of the business logic of CiviCRM, that is to say the part of CiviCRM that
-defines what it does and how it behaves (e.g. that allows people to register on
-    events) is found in the CRM directory ('CIVICRM_ROOT/CRM').  Looking in
-this directory, you'll find directories for core CiviCRM functionality like
+Most of the business logic of CiviCRM, is found in the CRM directory ('CIVICRM_ROOT/CRM').
+This logic is the part of CiviCRM that
+defines what it does and how it behaves
+(e.g. that allows people to register on events)
+In this directory, you will find directories for core CiviCRM functions like
 contacts, groups, profiles, deduping, importing, and the CiviCRM components
 like CiviCampaign, CiviMail, Pledges, etc.
 
 Each of these directories is slightly different depending on what they do but
-there are some subdirectories that you'll find in most of them, for example
-BAO, DAO, Form and Page.  So what can you expect to find in these directories?
+there are some common subdirectories: BAO, DAO, Form and Page.
 
 ### DAO
 DAO stands for data access object.  Code in this directory exposes the contents
@@ -62,8 +55,8 @@ of the database.  The DAOs are automatically generated for each release based
 on the data schema.  DAO objects tend to be instantiated in BAO classes.
 
 The DAO has a property for each field (using the actual field name, not the
-    unique name).  They also have standard create retrieve update delete type
-functions, etc.
+unique name).  They also have standard CRUD (create retrieve update delete) type
+functions, etc. <!--fixme why the etc? what else?? -->
 
 ### BAO
 BAO stands for business access object.  BAOs map to DAOs and extend them with
@@ -73,25 +66,27 @@ activity is created, or create activities and populating custom fields when a
 pledge is created.
 
 ### Form
-In general each page in CiviCRM which contains a form maps to a file in one of
+In general each form page in CiviCRM maps to a file in one of
 the form directories.  Form files contain a class that extends CRM_Core_Form.
-This class has different methods that are used before the form is displayed to
-do things like check permissions, retrieve information (preProcess), display
-the form (buildForm), validate the form (formRule) and carry out tasks once the
-form is submitted (postProcess).  Forms can take information from the BAO to be
-displayed to users and call the BAO on submission. In general, each form has an
-associated template (see below) which is used to create the html of the form.
-Perhaps the best way to get to grips with the Forms is by experience and
-experimentation.
+This class has different methods that the core calls before display to
+check permissions, retrieve information (`preProcess`), display
+the form (`buildForm`), validate the form (`formRule`) and carry out tasks once the
+form is submitted (`postProcess`).  Forms can diplay information from the BAO
+to users and then call the BAO on submission. Generaly each form has an
+associated template (see below) which defines the form's html.
+
+!!! tip
+    Perhaps the best way to get to grips with the Forms is by experience and
+    experimentation.
 
 ### Page
-If a CiviCRM screen isn't a Form, it is probably a page.  Pages files contain a
+If a CiviCRM screen is not a Form, it is probably a page.  Pages files contain a
 class that extend CRM_Core_Page.  Similar to the form class, Pages have methods
 that are called before the page is displayed to control access, set the title,
-     etc. (preProcess), and when the page is displayed (run). Pages tend to
-     take information from the BAO to be displayed to users. In general, each
-     page has an associated template (see below) which is used to create the
-     html of the page.
+etc. (`preProcess`), and when the page is displayed (`run`). Pages tend to
+take information from the BAO to be displayed to users. In general, each
+page has an associated template (see below) which is used to create the
+html of the page.
 
 ### xml
 This directory contains a menu directory which maps urls to CRM form or page
@@ -104,7 +99,7 @@ map to a form or page class.  CiviCRM chooses a template for the form or page
 based on the class name.
 
 For example, the class CRM_Member_Form_MembershipRenewal looks for a template
-in templates/CRM/Member/Form/MembershipRenewal.tpl
+in `templates/CRM/Member/Form/MembershipRenewal.tpl`.
 
 Templates are written in smarty, a common PHP template engine.  Variables can
 be passed to smarty using the assign() method which is available to all Form
@@ -145,7 +140,7 @@ are located in Civicrm/xml/Schema. All the folders within this directory also
 have folders in the main CRM folder which contain a DAO folder and generally a
 BAO folder too.
 
-Looking in CiviCRM/xml/Schema/Pledge we see 4 files:
+Looking in `CiviCRM/xml/Schema/Pledge` we see 4 files:
 
 files.xml
 Pledge.xml
@@ -157,35 +152,15 @@ build both the DAO files and the new database sql generation script.
 
 The XML describes fields, foreign keys and indexes, an example of a field definition is:
 
-<field>
-       <name>amount</name>
-       <uniqueName>pledge_amount</uniqueName>
-       <title>Total Pledged</title>
-       <type>decimal</type>
-       <required>true</required>
-       <import>true</import>
-       <comment>Total pledged amount.</comment>
-       <add>2.1</add>
+```
+  <field>
+    <name>amount</name>
+    <uniqueName>pledge_amount</uniqueName>
+    <title>Total Pledged</title>
+    <type>decimal</type>
+    <required>true</required>
+    <import>true</import>
+    <comment>Total pledged amount.</comment>
+    <add>2.1</add>
   </field>
-
-## When should I edit core CiviCRM?
-The above should have given you a reasonable idea of what the CiviCRM codebase
-looks like.  Remember that most of the time, editing the core codebase directly
-is not the recommended way for developers to customise and extend CiviCRM.
-CiviCRM has two version releases per year so direct edits to the core codebase
-will create upgrade issues for you.
-
-There are other recommended ways for the majority of scenarios - for example
-extensions, the APIs and hooks. Be sure that any edits that you make to the
-core codebase are really necessary.
-
-To help you decide, here are a couple of principles:
-
-- Bug fixes should always be applied to core. Information on how to submit your
-  bug fix will be added soon.
-- Some (but not all) enhancements to existing features may be best applied to
-  core, especially if they would be useful to others.
-- New features should generally be packed as Extensions.
-- If you aren't familiar with CiviCRM, by far the best way to get a sense if
-  you should be editing core is by talking with the CiviCRM developer community
-  on IRC, the forums, etc.
+```

docs/core/hacking.md

+## When should I edit core CiviCRM?
+
+Remember that most of the time, editing the core codebase directly
+is not the recommended way for developers to customise and extend CiviCRM.
+
+CiviCRM has two version releases per year so direct edits to the core codebase
+will create upgrade issues for you. blah
+
+There are other recommended ways for the majority of scenarios - for example
+extensions, the APIs and hooks. Be sure that any edits that you make to the
+core codebase are really necessary.
+
+To help you decide, here are a couple of principles:
+
+- Bug fixes should always be applied to core. Information on how to submit your
+  bug fix will be added soon. <!--fixme!! -->
+- Some (but not all) enhancements to existing features may be best applied to
+  core, especially if they would be useful to others.
+- New features should generally be packed as Extensions.
+- If you aren't familiar with CiviCRM, by far the best way to get a sense if
+  you should be editing core is by talking with the CiviCRM developer community.

mkdocs.yml

@@ -37,9 +37,12 @@ pages:
   # - Custom Reports: extensions/custom-reports.md
   # - Custom Searches: extensions/custom-searches.md
   # - Payment Processors: extensions/payment-processor.md
+- Core code:
+  - Hacking the core: core/hacking.md
+  - Architecture: core/architecture.md
 - Miscellaneous:
    - Extension Lifecycle: extend-stages.md
    - Markdown: markdownrules.md
-   - hookref-old: hookref-old.md
+   # - hookref-old: hookref-old.md
 - Deprecated:
    - Building CiviCRM from source: develop-deprecated.md