Feature dei documentation

documentation/conf.py

@@ -141,7 +141,7 @@
 # This started causing errors, so removing it from the conditional statement and replacing it with the above lines
 # import os
 # on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-# 
+#
 # if not on_rtd:  # only import and set the theme if we're building docs locally
 #     import sphinx_rtd_theme
 #     html_theme = 'sphinx_rtd_theme'
@@ -406,6 +406,56 @@
         use_titles=True,
     )
 
+#-------------------------------------------------------------------------------------------
+# Fetch extension schemas at build to allow drawing schema tables in the extensions section
+#
+# Matt added this to deal with the problem where we need to draw schema tables for
+# extensions but the extension schemas are managed externally.
+#-------------------------------------------------------------------------------------------
+
+import requests
+
+schema_extensions = ['dei'] # ADD NEW EXTENSIONS HERE
+
+# IMPORTANT: Update this URL when the dei extension is merged in
+base_url = "https://raw.githubusercontent.com/ThreeSixtyGiving/extensions-registry/main/extensions/"
+
+if not os.path.exists("./extras"):
+    os.mkdir("./extras")
+
+if not os.path.exists("./extras/extensions/"):
+    os.mkdir("./extras/extensions/")
+
+for extension in schema_extensions:
+    # Make a directory for the extension schemas inside the extras directory
+    extension_path = f"./extras/extensions/{extension}"
+    if not os.path.exists(extension_path):
+        os.mkdir(extension_path)
+        os.mkdir(f"{extension_path}/codelists")
+
+    # Fetch the registry entry and parse the JSON
+    registry_entry = json.loads(requests.get(f"{base_url}/{extension}.json").text)
+
+    # Fetch each of the schemas
+    for schema in registry_entry['schemas']:
+        schema_content = requests.get(schema['uri']).text
+
+        with open(f"{extension_path}/{schema['target']}", 'w') as schema_file:
+            schema_file.write(schema_content)
+
+    # Fetch each of the codelists
+    for codelist in registry_entry['codelists']:
+        codelist_content = requests.get(codelist).text
+        codelist_name = codelist.split('/')[-1]
+
+        with open(f"{extension_path}/codelists/{codelist_name}", 'w') as codelist_file:
+            codelist_file.write(codelist_content)
+
+#-------------------------------------------------------------------------------------------
+#-------------------------------------------------------------------------------------------
+# End fetch extension schemas at build
+#-------------------------------------------------------------------------------------------
+
 #mv README.md 360-giving-schema-titles.csv/
 
 

documentation/extensions/dei/governance.md

@@ -0,0 +1,32 @@
+# Governance and Versioning
+
+As an extension to the 360Giving Data Standard, the DEI Extension is managed outside of the [governance process](https://standard.threesixtygiving.org/en/latest/about/governance/) of the 360Giving Data Standard itself.
+
+[360Giving](https://threesixtygiving.org/) is the steward of the DEI Extension. Our CEO is responsible for its day-to-day management, supported by a Product Manager and an external specialist technical team, [Open Data Services Coop](https://opendataservices.coop/).
+
+## Aims and Approach
+
+Our aims and approach for maintaining the DEI Extension are as follows:
+
+1. Compatibility with the 360Giving Data Standard: to maintain compatibility with the latest release of the 360Giving Data Standard.
+
+2. Compatibility with the DEI Data Standard: to maintain compatibility with the DEI Data Standard itself whenever possible. Updates to the DEI Extension will be issued in a timely manner to bring it in line with changes to the taxonomy structure and codes included in the DEI Data Standard, as well as any guidance about how to apply this to publishing the data alongside 360Giving data.
+
+3. Use semantic versioning: to use semantic versioning to version this extension. MAJOR updates will not be compatible with previous versions of the extension, MINOR updates will add new features that are backwards compatible, and PATCH updates will fix bugs and amend documentation.
+
+4. Consider stakeholders’ needs in the revision process: to consider stakeholders’ needs and follow [360Giving Data Standard revision processes](https://standard.threesixtygiving.org/en/latest/about/governance/#the-revision-process) when making updates to the DEI Extension.
+
+
+## Versions
+
+The DEI Extension is versioned using [Semantic Versioning](https://semver.org/).
+
+The version number of the DEI Extension and update processes and schedules are *separate* from each: the [360Giving Data Standard](https://standard.threesixtygiving.org/en/latest/about/governance/#versions); and the [DEI Data Standard](https://www.funderscollaborativehub.org.uk/collaborations/dei-data-standard).
+
+This means there may be times when data shared using the DEI Extension does not match the latest version of the DEI Data Standard.
+
+The version number and all notable changes are documented by Release via the Changelog.
+
+## Changelog
+
+All notable changes to the DEI Extension are documented by Release via the extension's [Github repository](https://github.com/ThreeSixtyGiving/360-dei/releases).

documentation/extensions/dei/guidance.md

@@ -0,0 +1,115 @@
+# DEI Extension guidance for publishers
+
+## Introduction
+
+This guide is for UK funding organisations that want to publish data collected using the DEI Data Standard alongside 360Giving grants data. It is designed to help you whether you are at the very beginning of your journey and planning your approach or preparing your data.
+
+This guidance provides further information about the DEI Data Standard and the 360Giving Data Standard’s DEI Extension which has been developed to support the sharing of DEI Data Standard data alongside 360Giving data.
+
+This isn’t a reporting process, it’s an opportunity to collect and share data that will create a knowledge base to support effective action to identify and target funding to address structural inequity.
+
+### How does publishing DEI Extension data relate to publishing 360Giving data?
+
+This guidance is for those who want to publish information using the DEI Data Standard in the context of their grant information. The guidance in this section focuses on the fields and codes defined in the DEI Extension.
+
+If you are new to publishing 360Giving data but are doing so with a view to also including DEI Data Standard data, we suggest you begin at the [Guidance for Publishers](../../../guidance). This will help you understand the key principles involved in publishing 360Giving data. Once you are familiar with the steps and process, you will be able use this guidance to understand how to integrate the DEI Data Standard data into your 360Giving data publication.
+
+If you are already a 360Giving publisher, or are otherwise already familiar with how to publish 360Giving data, this guidance will help you integrate the DEI Data Standard data alongside your existing 360Giving grants data.
+If you publish or plan to publish data about grants made to individuals, it is not possible to publish DEI data alongside your 360Giving grants data as, combined with other data published, this risks making grant recipients personally identifiable. However, it is possible to collect this data and share it in aggregate, for example on your own website. For more on this, see the [data protection section](../../../individuals/publisher-guidance/#demographic-data) of our grants to individuals guide.
+
+
+<div class="box box--teal">
+    <p>
+      If you are familiar with the DEI Data Standard and have already collected some DEI data, skip to the <a href = "#about-the-dei-extension">DEI Extension guidance section</a>
+       </p></div>
+
+## About the DEI Standard
+
+The [DEI (Diversity, Equity, and Inclusion) Data Standard](https://www.funderscollaborativehub.org.uk/dei-data-standard) was created by an independent working group of UK funders, known as the **DEI Data Group**, who believe that without an effective framework to capture equity data there can be no effective action to identify and target funding to address structural inequity.
+
+The DEI Data Group agreed on a **shared framework** (classifications, language and approach) which aims to categorise organisations either led by, or targeting and supporting groups experiencing structural inequity.
+
+There are three key elements to the framework.
+
+* The first is the **taxonomy** which is the classification system used to describe population groups
+* The second is the **approach** to collecting the data. In the context of grantmaking, these taxonomies may be applied to the following three areas:
+  - People receiving primary benefits/service users of the project or the organisation
+  - Mission and purpose of the organisation
+  - Leadership of the organisation
+* The third and final area of the framework is **guidance** to support the consistency of application by funders. This aims to make it easier for applicants to grant programmes as they will be asked the questions in a similar way, and for funders to benchmark and compare their programmes with their peers.
+
+The guidance provided by the DEI Data Group covers key considerations for implementing the DEI Data Standard, which include:
+
+- What level of granularity of the taxonomy data will be collected?
+- Which areas of the application approach should be applied?
+- How will the data be used by your organisation?
+- At what point in the grantmaking process should the data be collected?
+- Is the data suitable for publication? Which statements and opt-outs have been made available to grantees about the DEI data they have provided?
+
+
+### Why collect and share DEI Data Standard data?
+
+Collecting and sharing DEI Data Standard information is intended to enable funders to understand whether the reach of the funding and their funding practices are equitable. Information shared in this way can then be used to inform funding strategies and specific funding programmes or approaches.
+
+It is important to note that the DEI Data Standard is about understanding **equity** rather than diversity. It aims to help funders to answer the question – is our grantmaking reaching communities facing structural inequity, and in particular is the money going to organisations led by people from those communities?
+
+The goal of developing the DEI Data Standard and framework for applying it was to increase the equity of grantmaking through having good quality and consistent data to monitor this, and to enable shared reporting, while also reducing the burden on applicants around data collection through grantmakers using a consistent approach.
+
+### How to collect DEI Data Standard Data
+
+The DEI Data Standard isn’t one size fits all and so it has been designed with options in how the data is collected to suit different funding approaches. For example a funder making a large volume of grants will probably make different choices to a funder who makes fewer grants.
+
+Full information about the DEI Data Standard, including details of the taxonomy and approach, and guidance on how to apply these to different grantmaking contexts can be found on the ‘The DEI Data Standard’ section of the [Funders Collaborative Hub](https://www.funderscollaborativehub.org.uk/dei-data-standard)
+
+It is recommended that you work through the DEI Data Standard Guidance and are clear on your aims, use, and approach **before** starting to plan your implementation of the DEI Extension. If you need support with deciding your organisation’s approach to using the DEI Data Standard then you can [get in touch with the DEI Data Group](https://www.funderscollaborativehub.org.uk/collaborations/dei-data-standard) via the contact details on their web page.
+
+As part of 360Giving’s support for the DEI Data Standard, we hold a regular free workshop, [**Introduction to the DEI Data Standard**](https://www.threesixtygiving.org/support/training-and-workshops/workshops/#free-publishing-workshops), which explains the key concepts and decisions for funders who want to start collecting DEI data.
+
+
+## About the DEI Extension
+
+The DEI Extension is an extension to the 360Giving Data Standard.
+
+360Giving has developed the DEI Extension to enable publication of DEI Data Standard information related to grants as a single dataset alongside 360Giving data. This ties the DEI Data Standard information directly to the context of the grant, making it easier to publish, manage, and analyse.
+
+The extension adds new fields to the 360Giving Data Standard which can be used to include data collected in accordance with the DEI Data Standard. This allows 360Giving tools to validate the DEI Data Standard information alongside the rest of the 360Giving data fields leading to better data quality for analysis and a better understanding of the equity of grantmaking and the collective grantmaking picture.
+
+Detailed technical information for the DEI Extension is available on the [Technical Reference](reference) page. It contains a reference for the fields and codes added by the DEI Extension.
+
+### What data can be published using the DEI Extension?
+
+The DEI Extension includes a number of fields which are important to understand the DEI Data Standard information provided. This includes the **answers** provided to DEI Data Standard questions. It also includes important context in which the questions were asked called **metadata**, which means data about the data itself.
+
+The DEI Extension follows the DEI Data Standard’s guidelines on the application of its taxonomy which is applied to grants in three different areas:
+
+- People receiving the primary benefits / service users – titled **Project** in the extension
+
+- The mission and purpose of the organisation – titled **Mission**
+
+- The leadership of the organisation – titled **Leadership**
+
+For each of these areas you may share the responses to the questions in the form of DEI Data Standard Taxonomy codes as well as free text responses, such as **lived experience** or **geographical** area.
+
+In addition to the fields for providing responses, there are also fields to provide metadata describing:
+
+- Whether questions were asked
+
+- How the questions were asked
+
+- What answer options were available to respondents
+
+- Whether there has been a response
+
+These metadata fields are important to contextualise the data to avoid ambiguity and support data users analysing and understanding the data correctly.
+
+### Why include metadata?
+
+Funders are able to make choices about how they implement the DEI Data Standard based on their specific context. This is an important feature of the DEI Data Standard, but leads to variations in the data collected which must then be contextualised to be understood correctly.
+
+For example, a funder making grants to small organisations or providing unrestricted funding for the benefit of the whole organisation might opt to only ask applicants questions about the Mission and the Leadership of the organisation because questions about the Mission and Project are likely to get the same responses. For another funder making grants for project work carried out by larger organisations, it may have opted to ask questions about all three application areas; Project, Mission and Leadership. A data user looking at data from these two funders side-by-side may not know whether the first funder didn't ask the Project question or whether that data is missing because the applicant didn't select any categories because the project did not target any particular population groups.
+
+The metadata fields in the DEI Extension address the issues caused by ambiguous or missing information by communicating the context in which the data was collected. They allow each funder to show which questions were asked about which application areas so that a data user can understand how to interpret the data correctly in each case.
+
+This is why it is important to understand the choices your organisation has made when implementing the DEI Data Standard and collecting DEI data, as this will allow you to fill in your DEI metadata appropriately. We recommend that you decide on your approach to collecting data using the DEI Data Standard before starting to prepare your DEI data for publication.
+
+Read our [guidance on the DEI Data Standard](#about-the-dei-standard) for links to further sources of information and support.

documentation/extensions/dei/index.md

@@ -0,0 +1,20 @@
+# Diversity, Equity, and Inclusion Extension
+
+This section provides publisher guidance and documentation for the DEI Extension provided by 360Giving. The DEI Extension is an extension to the 360Giving Data Standard which allows [Diversity, Equity, and Inclusion (DEI) Data Standard](https://www.funderscollaborativehub.org.uk/dei-data-standard) data to be published alongside [360Giving Data Standard](https://www.threesixtygiving.org/data-standard) data so that it can be validated and used in 360Giving tools.
+
+The DEI Data Standard is developed and maintained by the [DEI Data Group](https://www.funderscollaborativehub.org.uk/collaborations/dei-data-standard), with technical support provided by 360Giving. Information about the DEI Data Standard is hosted on their section of the Funders Collaborative hub.
+
+The DEI Extension has been developed and is maintained by [360Giving](https://www.threesixtygiving.org/) to support new and existing 360Giving publishers to include DEI Data Standard data in their 360Giving data files.
+
+The following guidance provides further information about the DEI Extension, DEI Data Standard and how to prepare and publish DEI data alongside 360Giving data.
+
+```eval_rst
+.. toctree::
+   :maxdepth: 3
+
+   guidance
+   prepare
+   reference
+   governance
+
+```