Policy for code lists

[jpmckinney]

To make code list changes easier to review independently, I propose the following policy.

Other issues:

• [ ] Define the existing classifications.
  • Do we put the definition as a comment above the classification?
  • This will make it easier to determine whether a new classification would overlap with an existing one.

---

For all lists:

• Format:
  • Classifications are in American English.
  • Classification keys are lowercase.
  • Classification values are titlecase.
  • Note: Some BILL_ACTION_CLASSIFICATION_CHOICES are not titlecase.
• Criteria for inclusion
  • A new classification must not be added if an existing classification would suffice.
  • There must be no words indicating the jurisdiction.
  • The classification must communicate a fact in the real world.
  • It must not be used to indicate some software state (e.g. "pending validation"), or some epistemological status (e.g. "unknown", "waiting for information").

For ORGANIZATION_CLASSIFICATION_CHOICES and BILL_CLASSIFICATION_CHOICES:

• Criteria for inclusion:
  • An organization classification must describe an executive, legislative or political organization.

For BILL_ACTION_CLASSIFICATION_CHOICES:

• Format:
  • Classification keys are hyphenated (no spaces).
  • The hyphenated parts should be ordered from general to specific, e.g. committee-passage-unfavorable.
• Criteria for inclusion:
  • A classification should only be prefixed by an organization classification if that additional information identifies a specific step in a predictable process.

[fgregg]

What about judicial organizations? We don't have any one using them, but it seems like they were contemplated since OCD Division include US District Court divisions.

[jpmckinney]

Right now, organizations include parties.

Yes, that's what I mean by "political".

Judicial? Sure. I didn't include as nothing in the code has touched that.

[fgregg]

K. I think we also need some documentation about what these different types of organizations mean. I don't really know what a "Corporation" is in this context, nor do I understand the difference between a "Department" and an "Agency"

[jpmckinney]

It often just comes down to what the organization's official name is. A jurisdiction may have an explanation for the difference between boards, committees, commissions, etc. but those definitions will vary between jurisdictions.

[fgregg]

So your proposal is to use the local name, and not to map organization types into cross-jurisdictional taxonomy?

On Sun, Feb 21, 2016 at 11:54 AM, James McKinney notifications@github.com wrote:

It often just comes down to what the organization's official name is. A jurisdiction may have an explanation for the difference between boards, committees, commissions, etc. but those definitions will vary between jurisdictions.

— Reply to this email directly or view it on GitHub https://github.com/opencivicdata/docs.opencivicdata.org/issues/59#issuecomment-186873755 .

773.888.2718

[jpmckinney]

Do you have a plan for how to do that? We can get some of the way there with the top-level organizations, but I don't think it's possible once you dig deeper into the org-tree.

[fgregg]

Right now, the best idea I have would be to require documentation of what the classifications mean and be thoughtful about merging pull requests.

On Sun, Feb 21, 2016 at 12:03 PM, James McKinney notifications@github.com wrote:

Do you have a plan for how to do that?

— Reply to this email directly or view it on GitHub https://github.com/opencivicdata/docs.opencivicdata.org/issues/59#issuecomment-186875188 .

773.888.2718

[jpmckinney]

Added to top of issue description. This issue is to describe what being thoughtful should entail.