Documentation Overview

[MattHJensen]

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

1. Tax law
   1. 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'.
   2. 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.
   3. 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
2. Data documentation *COMING SOON
3. Methodological documentation *COMING SOON
4. API documentation *COMING SOON
5. Contributor documentation *COMING SOON
6. User documentation *COMING SOON
7. 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.
8. Webapp documentation
   • [ ] describe how to modify multiple years, with an example
   • [x] 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.