added descriptions of the EIA861 data

docs/templates/eia861_child.rst.jinja

@@ -1,11 +1,21 @@
 {% extends "data_source_parent.rst.jinja" %}
 
 {% block background %}
-EIA Form EIA-861 (and the short form EIA-861S) make up the Annual Electric Power
-Industry Report, collecting data from distribution utilities and power marketers.
-It is a census of all United States electric utilities. As of 2023 PUDL
-only incorporates the annual data, but there's also a less detailed monthly `Form
-EIA-861M <https: //www.eia.gov/electricity/data/eia861m />`__.
+EIA Form EIA-861 (and the short form EIA-861S) make up the Annual Electric Power Industry Report.
+This survey is a census of all U.S. electric utilities and collects information about retail
+sales of electricity and associated revenue on an annual basis.
+
+
+As of 2023, the EIA-861 Form is organized into the following schedules:
+
+* **Schedule 1:** Identification
+* **Schedule 2:** Energy Sources data
+* **Schedule 3:** Distribution information
+* **Schedule 4:** Sales data
+* **Schedule 5:** Mergers and/or Acquisition information
+* **Schedule 6:** Demand-side Management Information
+* **Schedule 7:** Net-Metering Programs Information
+* **Schedule 8:** Service Territory Information
 
 There are more than 20 different spreadsheets included in the annual zipfiles. For
 details, see the `official EIA-861 page <{{ source.path }}>`__
@@ -18,12 +28,36 @@ details, see the `official EIA-861 page <{{ source.path }}>`__
 {% endblock %}
 
 {% block availability %}
+PUDL incorporates all available EIA-861 data (except the 2019 data) dating back to 2001.
+Earlier data from the forms EIA-861 (utility, Sales to Ultimate Customers, and Operational data),
+and EIA-861S (Sales to Ultimate Customers) exists for the years 1990-2000, but is not yet included in PUDL.
+As of 2023, PUDL only incorporates the annual data, but there's also a less detailed
+monthly `Form EIA-861M <https: //www.eia.gov/electricity/data/eia861m />`__.
 {% endblock %}
 
 {% block respondents %}
+The Form EIA-861 must be completed by electric power industry entities such as, but not limited to,
+electric utilities, all Demand Side Management (DSM) Program Managers (entities responsible for
+conducting or administering a DSM program), wholesale power marketers, energy service providers,
+electric power producers, transmission owners, transmission operators, and Third Party Owners of
+solar PV (TPO). Responses are collected at the operating company level (not at the holding company level).
+EIA-861S is intended for smaller bundled-service utilities and requires less detailed responses.
+
+EIA-861 and EIA-861S forms focus on annual data collection.
+However, respondents respond to either Form EIA-861 or Form EIA-861S and never both.
 {% endblock %}
 
 {% block original_data %}
+EIA typically publishes 861 data from the prior year in two rounds: an early release in the summer and a final release in the fall.
+The data are published on the EIA website and distributed as a collection of spreadsheets.
+The content of the spreadsheets varies from year to year as the questions in the form are updated.
+EIA also periodically changes the naming and structure of the spreadsheets without warning.
+Older “final” data may also be revised several years after it was published.
+To ensure reproducible analyses, we archive `versioned snapshots of the EIA-861 data on Zenodo <https://zenodo.org/records/10204708>`__.
+These archives are periodically refreshed with new data from the `EIA website <{{ source.path }}>`__.
+
+To understand the details of how the form and data have evolved over time,
+we recommend reading the Form Instructions from different years, linked above.
 {% endblock %}
 
 {% block notable_irregularities %}
@@ -36,4 +70,6 @@ details, see the `official EIA-861 page <{{ source.path }}>`__
 * We also have not yet integrated the Balancing Authority and Utility IDs reported in
   the EIA-861 into our entity tables, so for the moment we don't have any foreign key
   constraints enabled on the EIA-861 tables.
+* We have not yet integrated the 2018 EIA-861S data. Details about this are
+  mentioned in issue :issue:`3654`
 {% endblock %}