Documentation Overview

[MattHJensen]

There are several types of documentation that we need for the microsimulation model.

1. Tax law
2. Parameters (params.json)
   • Each parameter should have an IRS reference describing where it shows up on the IRS forms
   • Each parameter should have a description.
   • Each parameter should have a notes section
     • describes any limitations of the param (e.g., reducing the standard deduction amount will not increase the number of itemizers since we have not yet imputed itemizations onto non-itemizers).
     • haircut parameters should be described better; we should explicitly point out that 1.0 removes whatever the haircut is applied to and 0 leaves it unchanged.
   • Each parameter should have a long-name that summarizes the param in a few words.
   • The parameter field will show up on the webapp besides it's long-name. The description, notes, and IRS reference will be combined and displayed if you hover over the information 'i'.
3. Tax logic (functions.py)
   • Each function in functions.py should have a doc string that describes the important inputs and outputs to the function.
     • Important inputs include all of those variables from the public use file that are used in the calculations.
     • Important outputs include all of those variables that are used later in the calculator.
   • Complex calculations and intermediate variables should be annotated for clarity.
4. Taxpayer characteristics spreadsheet
   • This will replace var_labels.txt.
   • Ensure all variable labels are correct.
   • Indicate the origin of the variable: is it from the puf, full file only, cps, imputed, other.
   • Indicate whether we calculate the variable for tax computation or use the ecode version.
   • Indicate where the variable can be found on the IRS forms.
   • Add a section that describes all non-taxpayer-characteristic variables, like puf, cmp, fixup, etc.
   • List the stage 1 factor
   • List the stage 2 target
5. Data documentation
   *COMING SOON
6. Methodological documentation
   *COMING SOON
7. API documentation
   *COMING SOON
8. Contributor documentation
   *COMING SOON
9. User documentation
   *COMING SOON
10. Documentation documentation (meta)
    • Describe each of the above types of documentation
    • Describe conventions (parameter names, doc string format, etc.)
    • Describe best way to contribute to each type of documentation.
    • Describe how to build the html locally
    • Describe how to connect RTD to your fork so that you can view the docs with the proper formatting.
11. Webapp documentation
    • describe how to modify multiple years, with an example
    • describe how CPI toggle works
    • note that rates should be entered as .01 rather than 1%
    • describe and show an example of modifying multiple years of parameters

[MattHJensen]

@rkuchan, @Amy-Xu, @jlyons871, @xiyuw123 This is a WIP. Feel free to chime in on what content should be included via the comments section, and I will incorporate your suggestions in the issue text.

This should ultimately replace should ultimately replace #186, #123, #94.

[MattHJensen]

This issue overwhelming and hasn't proven to be constructive. Since I opened it and no one else has chimed in, I'll take the prerogative to close it.