Various suggested doc updates

[ryantibs]

Hi all, cc @Akvannortwick @dfarrow0 @capnrefsmmat @krivard @RoniRos

Been peeking at our documentation site now, and I have various suggested updates. Wanted to bring them here for discussion and if we converge on them, then perhaps @Akvannortwick can tackle them. These are in "visitation order" as I navigate down the menu bar on the left.

1. On the "Home" page, the title should be "Delphi Epidata API". And the first sentence should begin "Delphi's Epidata API provides ...".

2. On this same page, the documentation link is broken ("... for all his help with the Epidata API documentation.")

3. On the "COVIDcast Epidata API" page, we should remove "Delphi’s COVID-19 Surveillance Streams". This is old language, AFAIK, and we scrapped the word "surveillance" back in April. I count two uses of the word "surveillance" on this page. Should use "Delphi's COVID-19 indicators", which has been our standard terminology for a while.

4. On this same page, we should change all examples that use the raw_cli signal to instead use the smoothed_cli signal. The latter is much more widely available (especially significant in the example that fetches available data for all counties). In general, would do a grep to find all usages of raw_cli and replace it with smoothed_cli, in our documentation site.

5. On the "API Clients" subpage under the COVIDcast Epidata API section, we shouldn't document the generic Epidata clients. This is confusing, in my opinion. I think we should move everything from the "Generic Epidata Clients" header and below to a new subpage under the "Epidata API (Other Epidemics)" section, and the link to this from the current "API Clients" subpage.

6. On the "Epidata API (Other Epidemics)" page, I think it's confusing that this is titled "Delphi Epidata API". Given that the "Home" page also should have the same title. I would rename this section something like "Epidata API (General Epidemics)" and then title the page the same way.
   https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html).

7. On this same page, we say "Note that our work on COVID-19 is available in the COVIDcast Epidata API documentation." Our work isn't available in the documentation, so we should rephrase this. Either described in the ... documentation, or available in the ... endpoint?

8. On this same page, the structure is a bit confusing and I think warrants a scrutinous pass. First of all, it's very long, and the table of contents appears at the end. (This table of contents also appears to describe the rest of the subpages in this section, that follow?) Also, it appears it looks like the "Code Samples" subpart of this page is pretty much a duplicate of the "Generic Epidata Clients" subpart of the "API Clients" page (under "COVIDcast Epidata API" section)? If so, then I would just move this to a new subpage (as recommended above). Also the "Related work" subpart is a duplicate of the "Related work" section available from the menu bar?

9. That said, the "Related work" section doesn't appear to be all that related to the API. These were early inspirations for some of the first data streams (digital surveillance via Google searches and Twitter), they weren't early inspirations the API. I actually think this part isn't worth keeping, it's so out of date. But maybe @dfarrow0 feels differently.

10. For consistency we should stick to "Title Caps" for titles / headers / subheaders, etc. It appears we mostly do that, but this breaks down in the "Epidata API (Other Epidemics)" page and then quite a bit in the "Epidata API Development Guide" and "New Endpoint Tutorial" pages.

11. This one is more of a comment. I'm just generally confused by what's an "endpoint" and what's a "source". On this page, we associate endpoints with sources, which would reveal a ton of endpoints if you scroll down and look at the tables. Is that right? So it's just an unfortunate class of nomenclature that within the covidcast endpoint (source) we have many data sources?

[RoniRos]

Let me add to this, re item 6 above:

• All occurrences of "Other Epidemics" should be changed to "Other Diseases" (e.g. in item 6 above).
• Now that we decided to use "Delphi Epidata [API]" throughout for referring to our epidemiological data API, we should also develop a unified way to refer to the various endpoints, in our documentation and elsewhere. Some suggestions would be: "The XYZ endpoint of the Delphi Epidata API", "the XYZ Delphi Epidata API", "the Delphi Epidata API for XYZ", or "the Delphi Epidata API (XYZ endpoint)". I believe @capnrefsmmat was planning to use "Data from Delphi COVIDcast. Obtained via the Delphi Epidata API" as the standard citation text.

[capnrefsmmat]

"Endpoint" has a specific technical meaning here, referring to different values for the source parameter in API calls. (Not data_source, but source; for example, everything in COVIDcast is requested with source=covidcast.) Different endpoints may accept different arguments and return data in different formats, depending on the endpoint.

A request for symptom survey data might have the URL parameters source=covidcast&data_source=fb-survey&signal=smoothed_cli. Other endpoints, like fluview, don't need data_source and signal parameters, because they only contain a single specific type of data.

[ryantibs]

There hasn't been much ensuing discussion which I take to mean that people are in general agreement? @Akvannortwick I don't know what your queue looks like but can you comment on when you'd be able to start on this? (And if not for a while, then remind me what's ahead of it?) Thank you.

[Akvannortwick]

@ryantibs I can start this today. Zach also suggested I go through the API documentation yesterday and make edits through a pr for others to review.