Contributor documentation

[jpmckinney]

Principles

• Results should be stable. It's okay for an update to a contracting process to cause a red flag to be newly raised. However, it is disfavored for an update to cause a red flag to be lowered. For example, while awards are pending, calculating some red flags can cause false positives. On the other hand, it's okay (and normal) for flag to be raised after an update.

• Keep data preparation separate from indicator calculation. (see comment in Fallback to parties array to determine roles #23)

---

• From comments on the user research report: "It should be possible for developers to read documentation on how to implement new red flags, with as little new code as possible."

[jpmckinney]

cc @juanpane @Ravf95. I'll update this issue when some documentation is ready.

[jpmckinney]

• When implementing an indicator, check whether there are any steps to add or edit for the prepare command. For example, when item_classification_scheme and currency are set in the defaults section, they are only applied to /bids/details/classification/scheme (not additionalClassifications, or other parts of the schema) and to /bids/details/value/currency, because we don't use other schemes or values in any implemented indicators yet.
• For the defaults section, so far, I've used it for all codelist fields (that appear in indicators). I don't know yet if defaults make sense for other types of fields yet.
• prepare should only warn about fields not being set if there is a configuration option that allows the user to set a default. (Otherwise, it's just noise. This is not a quality assessment tool. We're just trying to make it easier to get indicator results.)

[jpmckinney]

• When documenting an indicator, the possible sections are:
  • Methodology (required), including example(s) and explanation
  • Interpretation (required)
  • Configuration
  • Exclusions
  • Assumptions
• Bold the first occurrence of each word in the methodology that can be configured or interpreted.

[jpmckinney]

If adding any code samples, can see if https://docs.rs/docmatic/latest/docmatic/ or https://docs.rs/doc-comment/latest/doc_comment/ will work to test example code.

Edit: Moved to #56

[jpmckinney]

• When adding indicator-specific settings, make all settings optional.