Merge pull request #970 from martinholmer/improve-param-docs

Improve documentation wrt new policy parameter naming and placing

README.md

@@ -28,8 +28,10 @@ At the moment there are three ways to start using the Tax-Calculator.
 
 The **first way** is to install the Tax-Calculator repository on your
 computer.  Do this by following the instructions in our [Contributor
-Guide](http://taxcalc.readthedocs.org/en/latest/contributor_guide.html)
-and then reading about our [testing procedures](TESTING.md).  This way
+Guide](http://taxcalc.readthedocs.io/en/latest/contributor_guide.html)
+and then reading about our [new parameter naming
+conventions](http://taxcalc.readthedocs.io/en/latest/parameter_naming.html)
+and our [testing procedures](TESTING.md).  This way
 allows you to read the source code and contribute enhancements to the
 source code.  While this way does not provide you with a
 representative sample of tax filing units, it does allow you to

TESTING.md

@@ -7,7 +7,9 @@ Tax-Calculator Testing Procedures
 This description of Tax-Calculator testing procedure is written for a
 person who wants to contribute changes to Tax-Calculator source code.
 It assumes that you have read the [Contributor
-Guide](http://taxcalc.readthedocs.org/en/latest/contributor_guide.html),
+Guide](http://taxcalc.readthedocs.io/en/latest/contributor_guide.html)
+and the [conventions about naming and placing new policy
+parameters](http://taxcalc.readthedocs.io/en/latest/parameter_naming.html),
 have cloned the [central GitHub Tax-Calculator
 repository](https://github.com/open-source-economics/Tax-Calculator)
 to your GitHub account and to your local computer, and are familiar

docs/source/make_local_change.rst

@@ -116,7 +116,7 @@ the charitable deduction floor rate looks like this:
 The new parameter's name consists of _ID (for Itemized Deduction), the
 deduction's name (_Charity), and the parameter's type (_frt for floor
 rate). For other parameter name and type abbreviations, see
-:doc:`parameter naming conventions</parameter_naming>`.
+:doc:`parameter naming and placing conventions</parameter_naming>`.
 
 The parameter has several attributes; the first year that we have a
 value for is 2013 and it is not adjusted for inflation. The charitable

docs/source/parameter_naming.rst

@@ -1,5 +1,5 @@
-Parameter Naming Conventions
-============================
+Parameter Naming and Placing Conventions
+========================================
 
 Parameter names have two components; the first component is an
 abbreviation for the parameter's tax category and the second component
@@ -101,3 +101,11 @@ Examples
 
    **_EITC_MinEligAge**: Earned Income Tax Credit minimum eligibility
    age for those with no EITC-eligible children
+
+Placing New Parameters in ``current_law_policy.json``
+-----------------------------------------------------
+
+All new parameters should be added to the ``current_law_policy.json``
+file in a location that maintains the convention that the policy
+parameters appear in that file in the order they are first used in the
+``functions.py`` file.