[Docs update] Restructuring the docs

[matamadio]

New documentation structure following the guidance in the ODS review.

SEE ONLINE PREVIEW

Section	Mode	Description of Content	RDLS existing content	Additional content
Primer (first page)	Explanation	Introduction to the domain, key concepts and reasons for standardising data, description of how the standard was developed and why, who the intended users are	Introduction, Taxonomies (but link to definition of RDLS Hazard taxonomy in other section), paragraphs in Data model pages discussion why certain attributes are included	Core standards, History
Schema reference	Reference	The schemas, codelists and rules that need to be followed to publish data	Data model attribute tables and examples, RDLS Hazard taxonomy
Guidance	How-to guides	step by step guides to implementing the data standard.	Implementation
Glossary			Key concepts
Support	How-to guides			support details

More in detail, navigation bar (sections) proposal:

• Primer (first page)
  • Core standards
  • History
• RDL schema
  • Overview
  • Hazard
  • Exposure
  • Vulnerability
  • Loss
• Guidance
  • Data preparation
    • Data formats
• Glossary
  • Risk definitions
• Support
  • External resources
  • Contacts

[stufraser1]

Reviewing:
Small edits committed directly on docs.mat branch.
Larger edits created on docs.mat.stu-? branches and PR created for @matamadio review

[stufraser1]

To do:

• add link to JSON templates

• Data_model class diagram to be updated as field names change in new JSON schema

Text accompanying tables to be updated from new JSON schema (tables updated automatically now)

• Data_model > hazard
• Data_model > exposure
• Data_model > vulnerability
• Data_model > loss
• Taxonomies

add new examples from CA data / others with RDL Collection links (see #135 for list)

• Data_model > hazard

• Data_model > exposure

• Data_model > vulnerability - [DATA] Vulnerability dataset examples #29

• Data_model > loss

• On packaging > Exposure, need to include an example of aggregated raster data, not just rasterised building footprint

• Include reference on disaster identifier and use of GLIDE number.

• add GLOSI taxonomy for schools to taxonomies.

• guidance on coding exposures - Exposure taxonomies format #18 - metadata defines the taxonomy being used; codes are included in the dataset - can be single string or multiple fields in the dataset.

[stufraser1]

GLIDE added at https://rdl-standard.readthedocs.io/en/dev/rdl/core-standards.html#hazard-data-standards

[duncandewhurst]

To be updated from new JSON schema

• Data_model > hazard
• Data_model > exposure
• Data_model > vulnerability
• Data_model > loss

#120 updates the reference documentation (formerly known as the data model section). The schema tables are now generated from the schema as part of the Sphinx build so they will always be up-to-date and manage.py includes a pre-commit script to update the sub-schema and codelist reference sections.

The diagrams, explanatory text and examples will need updating once the schema updates are done.

[duncandewhurst]

From #120 (review):

We also need to update the examples for each section to make a range of examples available with the JSON implementation of the metadata rather than tabulated values. This could include snippet of JSON in the documentation, or a link out to the metadata file if larger.

[matamadio]

Suggest to make longer tables (such as in codelists) collapsible, or other way to make the page more readable.

[duncandewhurst]

@stufraser1 @matamadio building on the work in this issue and the proposed updates to the landing page in #170, I've been thinking about the structure and framing of the documentation and have the following proposal on which I would like your feedback. Implementing this is mostly a case of renaming/reorganising existing content, although there a couple of new pages to author.

The objectives of the proposed updates to the structure and landing page content are: to clearly differentiate the concepts of metadata and risk datasets and to explain the role of RDLS in relation to those concepts; to provide a clear introduction to RDLS for new readers; and to provide make it easier for returning readers and implementers to find the information that they need.

Structure

Section	Content
Introduction
-- What is the RDLS?	New content: A high-level description of the scope and content of the standard, including a summary of structure of the metadata standard (datasets, resources, hazard metadata, exposure metadata, vulnerability metadata, loss metadata) and the role of the schema and codelists
-- Why use the RDLS?	Existing content from use cases page
-- How do I implement the RDLS?	New content: A high-level summary of how to implement RLDS (publish metadata according to the schema, follow guidance on packaging and formatting risk datasets) and supporting tools (spreadsheet template, conversion and validation tool)
-- How does RDLS relate to existing standards	Existing content from core standards page and integrate content from taxonomies page about 3rd party taxonomies
Metadata reference
-- Schema reference	Existing content from schema reference page
-- Schema browser	Existing content from schema browser page
-- Codelists	Existing content from codelist reference page and integrate content from taxonomies about RDLS taxonomies
Guidance
-- How to publish RDLS metadata	New content, building on RDL metadata page
-- How to publish risk datasets
---- How to package risk datasets	Existing content from data packaging page]
---- How to format risk datasets	Existing content from data formats page
Glossary	Existing content from glossary of terms page
About
-- Contacts	Existing cnotent from contacts page
-- Changelog	Existing content from changelog page
-- Governance	Existing content from governance page
-- License	Existing content from license page
-- History and roadmap	Existing content from history and roadmap page

Landing page content

The Risk Data Library Standard (RDLS) is an open metadata standard for describing risk datasets used in climate and disaster risk assessments.

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 key feature of the RDLS is the metadata standard for describing hazard, exposure, vulnerability, and loss datasets. Whilst the RDLS does not seek to standardise risk datasets themselves, in addition to the metadata standard, it provides guidance on packaging and formatting for risk datasets.

The RDLS is curated by the Global Facility for Disaster Reduction and Recovery 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.

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.

To help you use RDLS effectively, the documentation includes the following sections:

• An introduction to the RDLS
• Reference documentation for the metadata standard
• Guidance on how to publish metadata in RDLS format and how to package and format risk datasets
• A glossary of risk terminology
• Background information about the RDLS, including how it is governed, its history and roadmap, and who to contact for more information

[stufraser1]

I think this is a lot clearer than the current landing page, From my perspective, please go ahead. @matamadio ?

[matamadio]

Yes, I like it. Please do.

[odscjen]

closing this as it's been addressed in #175