merge with dev for docs update

GFDRR · Jun 26, 2023 · 0365a05 · 0365a05
2 parents 3965a28 + 04e66ca
commit 0365a05
Show file tree

Hide file tree

Showing 54 changed files with 1,693 additions and 1,299 deletions.
diff --git a/developer_docs.md b/developer_docs.md
@@ -19,7 +19,7 @@ The preferred approach for making changes to the standard is to use a [local dev
 
 1. Agree on a proposal in a [GitHub issue](https://github.com/GFDRR/rdl-standard/issues).
 1. Create a branch from the `dev` branch.
-1. Make your changes.
+1. Make your changes. Do not use normative keywords in non-normative content. For more information, see [normative and non-normative content in RDLS](https://docs.google.com/document/d/13g1SZO3ZSHbkymtc69lQOu9vB9vlZVZnodAcxC50l1M/edit#). 
 1. [Build the documentation](#build-the-documentation), resolve any errors and preview your changes locally.
 1. Commit your changes to your branch and push it to GitHub. Your changes are available for anyone to preview at [https://rdl-standard.readthedocs.io/en/{branch name}](https://rdl-standard.readthedocs.io/en/{branch name}).
 1. [Create a pull request](https://github.com/GFDRR/rdl-standard/compare):

diff --git a/docs/_static/extra.css b/docs/_static/extra.css
@@ -39,6 +39,9 @@ display: block;
 h1, h2, h3 {
   color: #0b3860;
 }
+h2, h3 {
+  margin-top: 25px;
+}
 
 ul {
 line-height: 1.7em!important;

diff --git a/docs/about/history/changelog.md → docs/about/changelog.md b/docs/about/history/changelog.md → docs/about/changelog.md
diff --git a/docs/about/contacts.md b/docs/about/contacts.md
@@ -0,0 +1,17 @@
+# Contacts
+
+## Risk Data Library team
+
+- Mattia Amadio (Consultant): [mamadio@worldbank.org](mailto:mamadio@worldbank.org)
+- Stuart Fraser (Consultant): [sfraser@worldbank.org](mailto:sfraser@worldbank.org)
+- Pierre Chrzanowski (RDL lead): [pchrzanowski@worldbank.org](mailto:pchrzanowski@worldbank.org)
+
+## World Bank Data Catalog team
+
+This team is responsible for review and publication of submitted datasets, and to assign datasets to the World Bank Data Catalog [Risk Data Library collection](https://datacatalog.worldbank.org/search/collections/rdl).
+
+- Kamwoo Lee: [klee16@worldbank.org](mailto:klee16@worldbank.org)
+- Gaurav Bhardwaj: [gbhardwaj1@worldbank.org](mailto:gbhardwaj1@worldbank.org)
+- Rochelle O’Hagan (DDH lead): [rohagan@worldbank.org](mailto:rohagan@worldbank.org)
+
+<br><hr>
diff --git a/docs/about/governance.md b/docs/about/governance.md
@@ -1,14 +1,14 @@
-# Risk Data Library Standard Governance
+# Standard governance
 
 This document provides an overview of the governance and processes used to develop the Risk Data Library Standard. The standard aims to define a data model, taxonomies and additional specifications to improve the discovery, management and exchange of risk data.
 
-This document is intended to be a useful reference point for anyone involved in contributing to the standard. It focuses on the roles, responsibilities and processes. This is intended to complete the [contributor guide](https://github.com/GFDRR/rdl-standard/blob/main/CONTRIBUTING.md) which outlines the range of ways in which contributors might support development of the standard.
+This document is intended to be a useful reference point for anyone involved in contributing to the standard. It focuses on the roles, responsibilities and processes. This is intended to complete the [**contributor guide**](https://github.com/GFDRR/rdl-standard/blob/main/CONTRIBUTING.md) which outlines the range of ways in which contributors might support development of the standard.
 
-<hr>
+______________________________________________________________________
 
 ## Our governance principles
 
-As a group we are committed to [the OpenStand principles](https://open-stand.org/about-us/principles/). These are five principles that guide our work:
+As a group we are committed to the [**OpenStand principles**](https://open-stand.org/about-us/principles/). These are five principles that guide our work:
 
 - **Due process**. Decisions are made with equity and fairness among participants. No one party dominates or guides standards development. Standards processes are transparent and opportunities exist to appeal decisions. Processes for periodic standards review and updating are well defined.
 - **Broad consensus**. Processes allow for all views to be considered and addressed, such that agreement can be found across a range of interests.
@@ -18,101 +18,68 @@ As a group we are committed to [the OpenStand principles](https://open-stand.org
 
 We are working to improve our process to ensure that we are living up to these principles. This document provides a reference point for our current practices.
 
-<hr>
+______________________________________________________________________
 
 ## Intellectual property
 
 All the outputs from this standards initiative are openly licensed under a CC-BY-SA 4.0 licence.
 
 Additional documentation and source code produced by this initiative will also be published under a suitable open licence. We encourage other organisations to similarly licence their work, so that it can be used for the benefit of the wider community.
 
-<hr>
+______________________________________________________________________
 
 ## Roles and responsibilities
 
 This project is currently managed by the Risk Data Library team working within the
 [Global Facility for Disaster Risk and Reduction](https://www.gfdrr.org/en).
 
-To guide development and adoption of the standards, in addition to open working through this github project, the team invites expert input via an Advisory Group and, as
+To guide development and adoption of the standards, in addition to open working through this GitHub project, the team invites expert input via an Advisory Group and, as
 required, specific Technical Working Groups.
 
 ### Advisory Group
 
-The RDL Advisory Group consists of experts in risk data management and analysis from
-the humanitarian sector, insurance industry and other related domains.
+The **RDL Advisory Group** consists of experts in risk data management and analysis from the humanitarian sector, insurance industry and other related domains.
 
 The Advisory Group will help to:
 
-1. ensure the development of the standard is informed by the needs of a broad selection
-   of stakeholders across a range of domains
+1. ensure the development of the standard is informed by the needs of a broad selection of stakeholders across a range of domains
 1. steer the development of the RDL standards, providing expert review on priorities, activities and major technical decisions.
-1. ensure that our work aligns with other relevant initiatives, to avoid
-   duplication of work and to build momentum around adoption of common standards
-1. identify opportunities for joint projects that can demonstrate the value of adopting the
-   RDL standards
+1. ensure that our work aligns with other relevant initiatives, to avoid duplication of work and to build momentum around adoption of common standards
+1. identify opportunities for joint projects that can demonstrate the value of adopting the RDL standards
 1. disseminate the impacts and outputs of the RDL project to other stakeholders
 
-Participation in the Advisory Group is by invitation only. The initial membership will
-consist of representatives from organisations who have contributed to the early
-development of the standard.
+Participation in the Advisory Group is by invitation only. The initial membership will consist of representatives from organisations who have contributed to the early development of the standard.
 
-Membership will be regularly reviewed. Please contact the team to discuss participation if
-you believe that you, or your organisation, are able to contribute.
-
-The Advisory Group will meet every two months. The agenda, slides and minutes from these
-meetings will be publicly shared via this Github forum.
+Membership will be regularly reviewed. Please contact the team to discuss participation if you believe that you, or your organisation, are able to contribute.
+The Advisory Group will meet every two months. The agenda, slides and minutes from these meetings will be publicly shared via this Github forum.
 
 ### Technical Working Groups
 
-At times we may create specific Technical Working Groups that will collaborate on
-development of specific aspects of the RDL standard. For example to develop taxonomies,
-or revise file formats or schemas.
-
-These Working Groups will have a clear remit and will coordinate their work through this
-github.
-
-Membership of these groups and participation in calls and workshops will be open to
-all participants. Depending on the scope of work, they may need to draw on expertise from a wider
-group of stakeholders.
-
-This model reflects the process of development of early versions of the standard, which involves
-convening a range of organisations around developing models for hazard, exposure and other types
-of data. This approach will help us to drawing on expertise, and seek focused input, from
-across a wide range of organisations.
+At times we may create specific Technical Working Groups that will collaborate on development of specific aspects of the RDL standard. For example to develop taxonomies, or revise file formats or schemas. These Working Groups will have a clear remit and will coordinate their work through this GitHub.
+Membership of these groups and participation in calls and workshops will be open to all participants. Depending on the scope of work, they may need to draw on expertise from a wider group of stakeholders.
 
-All working documents, issue reporting and decisions made within these groups will be
-reviewed and communicated via this repository.
+This model reflects the process of development of early versions of the standard, which involves convening a range of organisations around developing models for hazard, exposure and other types of data. This approach will help us to drawing on expertise, and seek focused input, from across a wide range of organisations.
+All working documents, issue reporting and decisions made within these groups will be reviewed and communicated via this repository.
 
-<hr>
+______________________________________________________________________
 
 ## How we collaborate
 
-At present our primary means of collaborating on the standard is via a set of open processes
-coordinated through this Github repository.
-
-We will use the:
+At present our primary means of collaborating on the standard is via a set of open processes coordinated through this Github repository.
 
 - [Discussions](https://github.com/GFDRR/rdl-standard/discussions) for general discussion around the scope and adoption of the standard
 - [Issues](https://github.com/GFDRR/rdl-standard/issues) to propose and discuss changes to the standard
 - [Project boards](https://github.com/GFDRR/rdl-standard/projects) to provide transparency of the current progress and priorities around its development
 
-<hr>
-
-## Managing and proposing changes
+______________________________________________________________________
 
-Anyone can propose changes to the specifications.
+## Proposing and managing changes
 
-The process for doing this is by [submitting an issue](https://github.com/GFDRR/rdl-standard/issues) using the appropriate template.
-We ask that you provide sufficient context to the proposed changes so that it can be discussed and reviewed by others.
+Anyone can propose changes to the specifications. The process for doing this is by [submitting an issue](https://github.com/GFDRR/rdl-standard/issues) using the appropriate template. The user must provide sufficient context to the proposed changes so that it can be discussed and reviewed by the [RDL team](contacts.md#risk-data-library-team) and other users.
 
-We will then:
+We encourage disussion and feedback, by requesting people leave comments on the issue. After leaving appropriate time for further comment, once we feel that a broad consensus has been achieved around the proposed changes, we will update the schema by releasing a new version of the specification.
 
-- regularly review issues, to ensure they are in scope for the project
-- encourage disussion and feedback, by requesting people leave comments on Github
-- once we feel that a broad consensus has been achieved around the proposed changes, we will update the current Working Draft with suitable wording
-- after leaving appropriate time for further comment, we will release a new version of the specification
-
-<hr>
+______________________________________________________________________
 
 ## Managing releases
 
@@ -124,5 +91,3 @@ Releases of the standard will follow the [semantic versioning](https://semver.or
 - Minor releases will be used for backwards compatible changes, e.g. additional of new optional attributes and relationships, or for simple clarifications and corrections
 
 To support gradual migration to the latest specification, we will maintain historical versions of the specifications in named folders in this repository.
-
-<br><hr>
diff --git a/docs/about/history/index.md b/docs/about/history/index.md
diff --git a/docs/about/index.md b/docs/about/index.md
@@ -1,11 +1,14 @@
 # About
 
+This user guide is written to support use of the Risk Data Library Standard.
+
 ```{eval-rst}
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
-   roadmap
-   history/index
+   contacts
+   changelog
    governance
    license
 

diff --git a/docs/about/license.md b/docs/about/license.md
@@ -1,5 +1,3 @@
 # License
 
 The content of this guide was prepared by GFDRR under the Risk Data Library Project and is licensed under [Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/legalcode).
-
-<br><hr>
diff --git a/docs/about/roadmap.md b/docs/about/roadmap.md
diff --git a/docs/data_model/exposure.md b/docs/data_model/exposure.md
@@ -28,20 +28,20 @@ The main features of an exposure dataset are specified by the **exposure model**
 Each exposure model includes one or more **assets**. Each asset could represent a single asset (e.g. one building) or a collection of assets (e.g aggregated buildings in an area).
 The exposure schema covers 4 categories and 11 occupancy types for consistent classification of assets across schema. The taxonomy source specifies the taxonomy string used to identify individual asset features within a dataset. Occupancy can be optionally assigned for night-time or day-time, e.g. to discern resident population from daily commuters.
 
-|**Required**| **Attribute** | **Description** | **Type** |
-|:---:| --- | --- | --- |
-|*| Category | Type of asset | <ul><li>Buildings<li>Indicators<li>Infrastructures<li>Crops, livestock and forestry</ul> |
-|*| Occupancy | Destination of use of the asset | <ul><li>Residential<li>Commercial<li>Industrial<li>Infrastructure<li>Healthcare<li>Educational<li>Government<li>Crop<li>Livestock<li>Forestry<li>Mixed</ul> |
-| | Occupancy time | Period of occupancy | <ul><li>Night<li>Day |
-| | Taxonomy source | Name of adopted taxonomy model | Text |
-| | Taxonomy code | String used by the taxonomy model to identify specific asset features | Text |
-|*| Value type | Element to which value refers | <ul><li>Structure<li>Content<li>Product<li>Other</ul> |
-|*| Value unit | Unit to measure exposed value | Unit code |
+| **Required** | **Attribute**   | **Description**                                                       | **Type**                                                                                                                                                    |
+| :----------: | --------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|      \*      | Category        | Type of asset                                                         | <ul><li>Buildings<li>Indicators<li>Infrastructures<li>Crops, livestock and forestry</ul>                                                                    |
+|      \*      | Occupancy       | Destination of use of the asset                                       | <ul><li>Residential<li>Commercial<li>Industrial<li>Infrastructure<li>Healthcare<li>Educational<li>Government<li>Crop<li>Livestock<li>Forestry<li>Mixed</ul> |
+|              | Occupancy time  | Period of occupancy                                                   | <ul><li>Night<li>Day                                                                                                                                        |
+|              | Taxonomy source | Name of adopted taxonomy model                                        | Text                                                                                                                                                        |
+|              | Taxonomy code   | String used by the taxonomy model to identify specific asset features | Text                                                                                                                                                        |
+|      \*      | Value type      | Element to which value refers                                         | <ul><li>Structure<li>Content<li>Product<li>Other</ul>                                                                                                       |
+|      \*      | Value unit      | Unit to measure exposed value                                         | Unit code                                                                                                                                                   |
 
-<br>Within one exposure model (e.g. one geospatial layer) there can be one or more **cost type** associated with damage to assets. For example, the cost of the building structure by square meter and the cost of the contents of a single building. The attributes are named accordingly within the datase, e.g. "Cost_structure" and "Cost_content".
-Additional **tags** attributes can be associated with an asset to link any information not envised in the exposure schema.
+<br>Within one exposure model (e.g. one geospatial layer) there can be one or more **cost type** associated with damage to assets. For example, the cost of the building structure by square meter and the cost of the contents of a single building. The attributes are named accordingly within the data, e.g. "Cost_structure" and "Cost_content".
+Additional **tags** attributes can be associated with an asset to link any information not specified in the exposure standard.
 
-<hr>
+______________________________________________________________________
 
 ## Examples
 
@@ -53,24 +53,20 @@ Two exposure datasets are shown together in the example: building footprints pol
 
 ![Exposure example](../img/sample_exp.jpg)
 
-|**Required**| **Attribute** | **Example** |
-|:---:| --- | --- |
-|*| Geographic coverage | Afghanistan |
-|*| Exposure category | Buildings |
-|*| Occupancy | Mixed |
-|| Taxonomy | OSM |
-|*| Value type | Structure |
-|\*| Unit of measure | USD |
-
-<br>
-
-|**Required**| **Attribute** | **Example** |
-|:---:| --- | --- |
-|*| Geographic coverage | Afghanistan |
-|*| Exposure category | Indicators |
-|*| Occupancy | Residential |
-|| Period of occupancy | Night |
-|*| Value type | Other |
-|\*| Unit of measure | Count |
-
-<br><hr>
+| **Required** | **Attribute**       | **Example** |
+| :----------: | ------------------- | ----------- |
+|      \*      | Geographic coverage | Afghanistan |
+|      \*      | Exposure category   | Buildings   |
+|      \*      | Occupancy           | Mixed       |
+|              | Taxonomy            | OSM         |
+|      \*      | Value type          | Structure   |
+|      \*      | Unit of measure     | USD         |
+
+| **Required** | **Attribute**       | **Example** |
+| :----------: | ------------------- | ----------- |
+|      \*      | Geographic coverage | Afghanistan |
+|      \*      | Exposure category   | Indicators  |
+|      \*      | Occupancy           | Residential |
+|              | Period of occupancy | Night       |
+|      \*      | Value type          | Other       |
+|      \*      | Unit of measure     | Count       |