Merge pull request #175 from GFDRR/43-restructure

docs: Restructure and update landing page content
GFDRR · Aug 8, 2023 · 152ae18 · 152ae18
2 parents 69dd313 + 1aece4b
commit 152ae18
Show file tree

Hide file tree

Showing 21 changed files with 135 additions and 871 deletions.
diff --git a/docs/about/changelog.md b/docs/about/changelog.md
@@ -80,5 +80,6 @@ This page lists changes to the Risk Data Library Standard.
 
 - [#111](https://github.com/GFDRR/rdl-standard/pull/111) - Add Global Library for Schools Infrastructure (GLOSI) to taxonomies.
 - [#172](https://github.com/GFDRR/rdl-standard/pull/172) - Re-write use cases as user stories, for data publisher and data user roles.
+- [#175](https://github.com/GFDRR/rdl-standard/pull/175) - Restructure documentation, rewrite landing page, add new introductory content.
 
 ### Other
diff --git a/docs/about/index.md b/docs/about/index.md
@@ -1,15 +1,15 @@
 # About
 
-This user guide is written to support use of the Risk Data Library Standard.
+This section provides background information on the Risk Data Library Standard (RDLS), including how it is governed, its history and roadmap, and who to contact for more information.
 
 ```{eval-rst}
 .. toctree::
    :maxdepth: 1
-   :hidden:
 
    contacts
    changelog
    governance
    license
+   roadmap
 
 ```
diff --git a/docs/rdl/roadmap.md → docs/about/roadmap.md b/docs/rdl/roadmap.md → docs/about/roadmap.md
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -1,6 +1,6 @@
 <!-- https://hackmd.io/VGiOi2NmQDS2Eu9jgUGNwQ -->
 
-# Glossary of terms
+# Glossary
 
 In this section, you will find definition of key concepts behind the RDLS including what is a disaster, how to reduce disaster risk through disaster disaster risk management and disaster risk assessment and what are the different types of risk data needed.
 

diff --git a/docs/guides/formats.md → docs/guides/datasets/formats.md b/docs/guides/formats.md → docs/guides/datasets/formats.md
@@ -1,4 +1,4 @@
-# Data formats
+# How to format risk datasets
 
 Risk data can be made of spatial or non-spatial data.
 
@@ -16,7 +16,7 @@ Below is a list of recommended and common geodata formats used for risk data.
 
 ```{note}
 Always prefer WIDE geodatabase table formatting instead of LONG format when working in GIS environment; by duplicating vector rows, the geospatial information is also duplicated, which cause the size of the data to increase exponentially, and slows down the spatial processing.
-![Screenshot](../img/tab_format.png)
+![Screenshot](../../img/tab_format.png)
 ```
 
 ### Raster data: GeoTIFF / COG (`.tif`)
@@ -51,7 +51,7 @@ Conversion from `.shp` to `.gpkg` is lossless and usually size-efficient. Where
 
 ```{note}
 Wide table formatting is preferred instead of long format.
-![Screenshot](../img/tab_format.png)
+![Screenshot](../../img/tab_format.png)
 ```
 
 ### Documents

diff --git a/docs/guides/datasets/index.md b/docs/guides/datasets/index.md
@@ -0,0 +1,12 @@
+# How to publish risk datasets
+
+This section provides guidance on how to publish risk datasets. For guidance on how to publish RDLS metadata, see [how to publish RDLS metadata](../metadata.md).
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+
+   formats
+   packaging
+
+```
diff --git a/docs/guides/preparation.md → docs/guides/datasets/packaging.md b/docs/guides/preparation.md → docs/guides/datasets/packaging.md
@@ -1,4 +1,4 @@
-# Data packaging
+# How to package risk datasets
 
 This section describes common data formats and file types developed during a risk assessment. For each of the hazard, exposure, vulnerability and loss components, it describes possible grouping of multiple files into minimal resources associated with a dataset, which can make it easier to find and download resources of the same type.
 
@@ -18,7 +18,7 @@ We also need to consider:
 
 ```{caution}
 In general, splitting raster datasets into smaller parts is not advised, according to self-dependency and completeness criteria. For data efficiency, always consider a larger extent than needed as to avoid cross-border artefacts. Instead of splitting rasters, consider storing the raster in an alternative format that maybe more size-efficient (see Formats sections).
-![Screenshot](../img/raster_clip.jpg)
+![Screenshot](../../img/raster_clip.jpg)
 ```
 
 Structuring risk data well when it is generated and before it is delivered to a client is important to ensure data folder are intuitive to search, and make dataset upload more efficient (and it is easier to do first time than changing the structure later). Decisions on how to structure risk data should be taken on a project-by-project basis, because there is a wide variety of how data are structured depending on the components of a project. For a country-scale analysis, we advise to follow the following structure of folders when preparing data for delivery / upload to a risk data catalog:
@@ -57,7 +57,7 @@ Hazard data typically include hazard maps representing one or more historical ev
 
 Generally, hazard data (footprints) takes the form of raster (geospatial grid) data (`GeoTIFF / COG`), less often as vector data (`gpkg`, `shp`). Supporting data (hazard curves, historical catalogue) could come as tables (`csv`, `xlsx`) or vector data (`gpkg`, `shp`).
 
-```{figure} ../img/hzd_tc.jpg
+```{figure} ../../img/hzd_tc.jpg
 ---
 align: left
 width: 98%
@@ -115,7 +115,7 @@ Exposure data typically describe the location, characteristics and value of indi
 
 Exposure geospatial data can take the form of vector (`gpkg`, `shp`), or raster (`GeoTIFF / COG`). In some cases, exposure comes as table (`csv`, `xls`).
 
-```{figure} ../img/exp_formats.jpg
+```{figure} ../../img/exp_formats.jpg
 ---
 align: left
 width: 98%
@@ -207,7 +207,7 @@ We recommend to group exposure data  using the following hierarchy:
 This hierarchy can be maintained also when packing all the data in one file (e.g. multiple csvs into one excel file), which is advised _unless specifically demanded by the data use_ (e.g. data are formatted for usage into a specific model).
 ```
 
-```{figure} ../img/vln_multi-table.jpg
+```{figure} ../../img/vln_multi-table.jpg
 ---
 align: left
 width: 98%

diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -1,17 +1,12 @@
-# Guides
+# Guidance
 
-Below is the guidance on best practices for dataset creation, packaging, metadata creation according to the RDL schema and distribution.
-
-- [Data preparation and packaging](preparation.md) of risk data files and folders
-- [Data formats](formats.md) recommended and supported formats to store and share data
+This section provides guidance on how to publish RDLS metadata and how to publish risk datasets.
 
 ```{eval-rst}
 .. toctree::
-   :maxdepth: 1
-   :hidden:
+   :maxdepth: 2
 
-   preparation
-   formats
-   rdl-metadata
+   metadata
+   datasets/index
 
 ```
diff --git a/docs/guides/rdl-metadata.md → docs/guides/metadata.md b/docs/guides/rdl-metadata.md → docs/guides/metadata.md
@@ -1,4 +1,4 @@
-# RDL metadata
+# How to publish RDLS metadata
 
 ## Adoption of the metadata schema
 

diff --git a/docs/img/structure.svg b/docs/img/structure.svg
diff --git a/docs/index.md b/docs/index.md
@@ -1,24 +1,22 @@
-<!-- https://hackmd.io/bdFuvXOfTXWzyHS44r1VXQ?both -->
-
 # Risk Data Library Standard
 
-The **Risk Data Library Standard (RDLS)** is an open data standard to make it easier to work with disaster and climate risk data. It provides a common description of the data used and produced in risk assessments, including **hazard**, **exposure**, **vulnerability**, and **modelled loss or impact**, data.
+The Risk Data Library Standard (RDLS) is an **open metadata standard** for describing risk datasets used in climate and disaster risk assessments.
 
-The Risk Data Library (RDL) project grew out of in-depth community consultation on improving access to **risk information** and is a result of the collective effort and ongoing support of internationally-recognised research institutions and established global partnerships with combined expertise across multiple hazards and all aspects of risk assessment. Its overarching purpose is to support disaster resilience work by making risk data better and easier to work with.
+The purpose of the RDLS is to enable risk reduction and resilience building by making it easier for risk data publishers to describe their datasets and for risk data users to identify datasets to use in their work. Many different organisations produce or use risk datasets, including humanitarian organisations, insurance companies, academic institutions and multi-lateral development banks.
 
-The RDLS gives risk experts a single language to describe hazard, exposure, vulnerability and modelled loss datasets. It gives datasets an underlying consistency that makes them highly interoperable and easily read by both people and machines. The schema contains labels for key metadata fields, making it easier to identify datasets hosted in different online catalogs without relying on external files or descriptions.
+The key feature of the RDLS is the metadata standard for describing **hazard**, **exposure**, **vulnerability**, and **loss** datasets. In addition to the metadata standard, the RDLS provides guidance on packaging and formatting for risk datasets, although it does not seek to standardise the contents of risk datasets.
 
-The RDLS has been developed by World Bank GFDRR for disaster and climate risk assessments but is intended to be used by anyone involved in generating or using disaster risk information.
+The RDLS is curated by the [Global Facility for Disaster Reduction and Recovery](https://www.gfdrr.org) and is intended for use by anyone involved in publishing or using disaster risk data. It is an open standard and community contributions are welcome.
 
-This documentation provides a technical overview of the RDLS and its different elements:
+The standard originated from in-depth consultations with the disaster and climate risk modeling community on improving access to risk datasets. It is the result of the collective effort and ongoing support of internationally-recognised research institutions and established global partnerships, bring together expertise in multiple hazards and all aspects of risk assessment.
 
-- [Overview](rdl/index.md): The core standards used within the RDLS, use cases and a roadmap
-- [Reference](reference/index.md): how to organize and link the data using the RDLS schema
-- [Taxonomy](taxonomies/index.md): details of taxonomies adopted by the RDLS
-- [Guides](guides/index.md): how to implement the RDLS in your project
-- [About](about/index.md): other information on the roadmap, history, governance and license
+To help you use RDLS effectively, the documentation includes the following sections:
 
-The RDL is a collaborative project managed by the [Global Facility for Disaster Reduction and Recovery (GFDRR)](https://www.gfdrr.org/) of the World Bank Group.
+- An [introduction](rdl/index.md) to the RDLS
+- [Reference](reference/index.md) documentation for the metadata standard
+- [Guidance](guides/index.md) on how to publish metadata in RDLS format and how to package and format risk datasets
+- A [glossary](glossary.md) of risk terminology
+- Background information [about](about/index.md) the RDLS, including how it is governed, its history and roadmap, and who to contact for more information
 
 ```{eval-rst}
 .. toctree::
@@ -27,7 +25,6 @@ The RDL is a collaborative project managed by the [Global Facility for Disaster
 
    rdl/index
    reference/index
-   taxonomies/index
    guides/index
    glossary
    about/index

diff --git a/docs/rdl/core-standards.md b/docs/rdl/core-standards.md
diff --git a/docs/rdl/how.md b/docs/rdl/how.md
@@ -0,0 +1,14 @@
+# How do I implement the RDLS?
+
+To implement the Risk Data Library Standard (RDLS), you need to author RDLS metadata to describe your risk datasets and publish it alongside your datasets. You can either author RDLS metadata from scratch, or convert existing metadata to RDLS format.
+
+You can use the following resources and tools to implement RDLS:
+
+- The RDLS spreadsheet template can be used to author RDLS metadata in spreadsheet format.
+- The RDLS metadata toolkit can be used to convert RDLS metadata from spreadsheet format to JSON format and to validate it against the RDLS schema.
+
+For step-by-step instructions on how to publish RDLS metadata, see the guidance on [how to publish RDLS metadata](../guides/metadata.md).
+
+In addition to the metadata standard, the RDLS provides [guidance on packaging and formatting risk datasets](../guides/datasets/index.md), although it does not seek to standardise the contents of risk datasets.
+
+If you have questions about the RDLS or need help implementing it, you can contact a member of the [Risk Data Library team](../about/contacts.md#risk-data-library-team).
diff --git a/docs/rdl/index.md b/docs/rdl/index.md
@@ -1,12 +1,14 @@
-# Overview
+# Introduction
 
-This section provides more detail on the core standards that are used within the Risk Data Library Standard, use cases for documenting risk data with the RDLS, and a roadmap for development.
+This section provides an introduction to the Risk Data Library Standard (RDLS).
 
 ```{eval-rst}
 .. toctree::
    :maxdepth: 1
 
-   core-standards
-   use-cases
-   roadmap
+   what
+   why
+   how
+   other-standards
+
 ```