Fix/clarify example for special election file naming conventions

[ghing]

In http://docs.openelections.net/archive-standardization/, the example for the special election seems a bit wonky:

Or a single file for a special general election for a single office:

20071211ohgeneralspecialhouse__5.csv

It seems to me like the office name should follow our standardized naming conventions and the district should be part of that office name. That is, it should not be separated from the rest of the office by a '__'. I believe the example should be:

20071211__oh__general__special__us_house_of_representatives_5.csv

[ghing]

Also, it seems like the order of election type and special flag differs between election slugs and filenames. I feel like we should make this the same. Any preference to special, election_type vs. election_type, special?

[dwillis]

I agree on the second part - the ordering of election type and special flag should be the same. I'm not sure about the convention for district, which is a separate field. Why would we not separate it?

[ghing]

@dwillis, I agree that district is a separate field. What confused me is that district wasn't mentioned as part of the filename "template". I amend my request to not separate district to be "we should update the docs to include how to handle district in an office-specifc result file. So, the "template" would read:

date__state__{party}__election_type__{special}__{jurisdiction}{office}__{{office_district}}__{reporting_level}.format

Any preference for the ordering of election type and special flag?

[dwillis]

I think it should be as your example shows: election_type then special. Cool?

[ghing]

@dwillis, I think that makes the most sense. So we update election slugs to reflect special following type. An example election slug would be:

md-2008-06-17-general-special

and not

md-2008-06-17-special-general

Are our formats for election slugs documented anywhere?

[dwillis]

I don't believe so, no. Here's how the dashboard does it.

[ghing]

Argh. So it looks like both the dashboard does it {{special}}-{{election_type}}. But, that the slug is not exposed through the API.

Which one do we change? Was there any motivation behind the ordering in one way or another? Are there any side-effects of changing one or the other that I'm missing?

[zstumgoren]

I think @dwillis might have implemented that, so not sure if there was a particular motivation behind the ordering. It does, however, reflect the proper way to describe the race in plain English: "a special general" is correct, afaik, rather than "a general special" (which would be something different semantically and not correct in this case).

That said, for purposes of file-naming conventions, I don't have strong feelings which way we go. Would be nice if the two were consistent though.

[dwillis]

I can't remember being really fired up about it, but yeah, special general seems more like how you would say it, although that's not really important. If we're not exposing the slug via the API, I think we should change it to {{election_type}}-{{special}} so we're consistent.

[ghing]

After looking through this thread, I think I prefer the way it is in the slug, special-general, especially given @zstumgoren observation about it being more semantic. I also think it's easier to change the file name generation rather than the slug. I'd like to update existing datasources to use special__general and update the docs accordingly. Any objections?

[dwillis]

No objection here.