Document fields in baked results

[ghing]

I realized when we were talking about differences between rows in baked RawResults because of different structures of the input files that we didn't have any documentation for the fields in the baked results. They're obvious for anyone who's looked at the models, but less so from someone just consuming the data.

Writing this will be fast and straightforward, but my one question is about where this should live, on www.openelections.net or on docs.openelections.net and link to it. I'm inclined toward putting it with the docs because that seems more maintainable. But I'm open to other opinions.

[dwillis]

+1 for docs.openelections.net

[benlk]

This may be state-specific, bake-specific data. How would you like to organize this?

[dwillis]

My inclination is to document the fields that aren't state-specific on docs.openelections.net and then have any state-specific stuff in state results repositories.

[benlk]

That makes sense.

After skimming through the docs, the most-likely-looking place to add this is https://github.com/openelections/docs/blob/master/dataentry.md#instructions, but that's not likely to be someplace where people who are using your data will look for descriptions of the column headers. Is there a better place?

After looking at Florida and Arizona, these columns seem common:

updated_at
id
start_date
end_date
election_type
result_type
special
office
district
name_raw
last_name
first_name
suffix
middle_name
party
jurisdiction
division
votes
votes_type
total_votes
winner
write_in
year

[dwillis]

I think this would be its own section on the docs site, maybe called "Results" with a subsection called "Common Fields"?

[benlk]

How do you want to handle writing definitions for http://docs.openelections.net/common-fields/ ?

[dwillis]

In my haze on Sunday I neglected to mention this