Merge pull request #64 from manaakiwhenua/iss-45

adds TOC; section on contributing including Discussions (closes #45)

Author: alpha-beta-soup

README.md

@@ -1,5 +1,35 @@
 # NZSLUC
 
+- [NZSLUC](#nzsluc)
+  * [Introduction](#introduction)
+  * [The New Zealand Standard Land Use Classification framework (NZSLUC)](#the-new-zealand-standard-land-use-classification-framework--nzsluc-)
+    + [Principles](#principles)
+      - [Prioritise atomic data (i.e. the decomposition of multi-dimensional attributes to observable, discrete characteristics; e.g. tenure).](#prioritise-atomic-data--ie-the-decomposition-of-multi-dimensional-attributes-to-observable--discrete-characteristics--eg-tenure-)
+      - [Be specific about purpose and scope.](#be-specific-about-purpose-and-scope)
+      - [Ensure extensibility.](#ensure-extensibility)
+      - [Use hierarchies where they are appropriate, required, and logically consistent.](#use-hierarchies-where-they-are-appropriate--required--and-logically-consistent)
+      - [Improve over time.](#improve-over-time)
+      - [Prioritise reproducible and transparent methodologies](#prioritise-reproducible-and-transparent-methodologies)
+      - [Accommodate multiple land uses.](#accommodate-multiple-land-uses)
+    + [Best practices](#best-practices)
+      - [Purpose](#purpose)
+      - [Scope](#scope)
+      - [Extensibility](#extensibility)
+      - [Data quality](#data-quality)
+      - [Semantic versioning](#semantic-versioning)
+      - [Metadata](#metadata)
+      - [Compatibility and reuse](#compatibility-and-reuse)
+      - [Definition of land](#definition-of-land)
+      - [Primary land use](#primary-land-use)
+      - [Provenance](#provenance)
+  * [Contribution](#contribution)
+  * [Glossary](#glossary)
+  * [Land Use Classification Systems](#land-use-classification-systems)
+  * [References](#references)
+  * [License](#license)
+
+## Introduction
+
 [![CC BY 4.0][cc-by-shield]][cc-by]
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12659959.svg)](https://doi.org/10.5281/zenodo.12659959)
 [![manaakiwhenua-standards](https://github.com/manaakiwhenua/nzsluc/workflows/manaakiwhenua-standards/badge.svg)](https://github.com/manaakiwhenua/manaakiwhenua-standards)
@@ -14,7 +44,7 @@ We propose a **land-use classification _framework_**  that includes principles a
 
 We also propose that **land use classification _systems_** be developed within the proposed framework. It is at the classification system level that a more concrete set of classes can be designed. It is unlikely that one classification system will be appropriate for integrating all data or for application in all use cases. The separation of concerns between the framework and the system allows for the development of multiple systems using a variety of properties, potentially only applicable at specific spatial or temporal scales, limited extents, or specific purposes (including for the purposes of confidentiality and indigenous data sovereignty). 
 
-# The New Zealand Standard Land Use Classification framework (NZSLUC)
+## The New Zealand Standard Land Use Classification framework (NZSLUC)
 
 The NZSLUC framework presents principles and best practices for designing land-use classification systems. Principles are intended to guide practitioners in how they use, reuse or design classification systems. 
 
@@ -24,7 +54,8 @@ The NZSLUC framework presents principles and best practices for designing land-u
 
 This [whakataukī](https://maoridictionary.co.nz/word/9903) envisions a mat-weaving analogy, which in this context recalls the reliance on multiple independent sources of input data, information, and knowledge from different people and organisations, with the ultimate aim of creating a shared understanding of land use as spatial information. A land-use map can be used by and for future generations to answer the enduring questions they have about land. 
 
-## Principles <!-- Informative -->
+<!-- Informative -->
+### Principles
 
 1. #### Prioritise atomic data (i.e. the decomposition of multi-dimensional attributes to observable, discrete characteristics; e.g. tenure). 
     - Classification systems should break down information being collected into individual (atomic, primitive, indivisible, discrete) attributes (diagnostic criteria) to expose important data-differentiating categories. 
@@ -45,7 +76,8 @@ This [whakataukī](https://maoridictionary.co.nz/word/9903) envisions a mat-weav
 1. #### Accommodate multiple land uses.
     - Classification systems should differentiate between secondary/co-located land uses (same place, same time) with intra-period land-use variation (same place, different time); e.g. rotational grazing, summer housing. 
 
-## Best practices <!-- Normative -->
+<!-- Normative -->
+### Best practices
 
 This collection of best practices is intended for producers of land-use information to benefit the consumers of land-use information.
 
@@ -67,29 +99,29 @@ The list of best practices for land use classification systems under this framew
 <!-- ![a worked example](figs/Framework-Classification-01.png)
 Fig N. Overview figure. -->
 
-### Purpose
+#### Purpose
 
 Land-use information is collected at multiple scales and for a variety of purposes, which, directly and indirectly, affect relevant decisions based on how that information is organised and/or applied. It is best practice to explicitly state the purpose for which land-use classification systems are designed, and this purpose will inform other decisions. When deciding on the purpose, consider what questions are likely to be answered if land-use information is systematically organised according to the classification system. An inter-agency central government report provides a useful framing for these questions as ‘enduring’; i.e. questions that do not really change over time, but the way we answer them (under a type of system or architecture) does (Stats NZ et al. 2013)[^1].
 
 Choice of geographical unit (e.g. property parcels) may make extension and reorganisation of land-use information difficult in some circumstances. Obviously there are pragmatic reasons for choices of this nature. Be mindful of knock-on effects stemming from what are effectively modelling decisions. Potential issues include alignment with existing tools or published data, computational (in)feasibility, the expected absence of finer-scale input data, restrictions on the use of required input data, and privacy. Where possible, a specification to use grids without pre-defined boundaries (such as [DGGS zones](https://docs.ogc.org/as/20-040r3/20-040r3.html) or raster grids) should be preferred. 
 
-### Scope
+#### Scope
 
 Land-use classification systems should describe their intended scope (e.g. spatiotemporal characteristics) and domain of discourse. Land-use classification systems need not be comprehensive: they may consider only a few land-use types and deem others as ‘out of scope’. For example, a classification of protected land may choose to classify all other land as non-protected without attempting more precise classification, according to the purpose of that classification system.
 
-### Extensibility
+#### Extensibility
 
 Ensure flexibility for land-use classification systems to interact with other land-use data and classification systems. This must include, for example, Māori attribute layers that maintain indigenous data sovereignty. 
 
 It should always be possible to extend or widen a classification system with more properties/attributes that can be determined by other users, such that information can be reorganised, re-presented, and corrected according to local priorities, and owned by individuals, hapū, and iwi without an expectation that this will be visible ‘upstream’.  
 
 Allowing both a class hierarchy and the annotation of multiple attributes is intended to enable the representation of whakapapa (genealogy) and whanaungatanga (origins, interdependencies, and interconnections) within a land-use classification system; and to represent the multiplicity of uses any area of land can simultaneously be associated with, which may go beyond the original intended purpose of a land-use classification system.
 
-### Data quality
+#### Data quality
 
 The quality of published land-use data should be described using a standard (e.g. ISO 19157-1:2023).
 
-### Semantic versioning
+#### Semantic versioning
 
 Any changes made to already-published land-use classification systems (including changes to the geographical unit or geographical scale) should be communicated to users using semantic versioning indicating major, minor and patch versions, e.g. v0.2.4. Once a version has been released, the contents of that version must not be modified; modifications should be released as an updated version.
 
@@ -100,7 +132,7 @@ The following are guidelines for semantic versioning:
 - Minor version for new or modified functionality in a backwardly compatible manner.
 - Patch version for backwardly compatible fixes and minor adjustments.
 
-### Metadata
+#### Metadata
 
 One or more established metadata standards should be used when publishing land-use data (whether public or private). Appropriate examples include:
 
@@ -109,23 +141,23 @@ One or more established metadata standards should be used when publishing land-u
 - DCAT-2 (Data Catalog Vocabulary, version 2)
 - Schema.org
 
-### Compatibility and reuse
+#### Compatibility and reuse
 
 Compatibility with existing New Zealand or international classification systems should be preferred in the design of classification systems. This should take the form of published concordances where such associations are possible. Examples of reuse and compatibility include Protected Areas Network of New Zealand (PAN-NZ) for conservation land, Australia and New Zealand Land Information Council (ANZLIC)for industrial categories, and DairyNZ classes. 
 
 This concept extends beyond land use narrowly considered and extends to land-use management practices and lists of commodities (i.e. established vocabularies). As an example, consider the [New Zealand Farm Data Standards](https://www.datalinker.org) glossaries. 
 
-### Definition of land
+#### Definition of land
 
 Classification systems should individually determine the definition of ‘land’ with reference to their stated purpose (e.g. whether it includes marine and terrestrial water bodies). It is also relevant for land-use classification systems to declare their extent of application (e.g. whether it should be applied to New Zealand's offshore islands, marine areas out to the Exclusive Economic Zone, the entire continental shelf, etc). There is no consensus as to whether a definition of ‘land’ can exclude uses such as aquaculture, marine conservation areas, fishing areas, mining permits, shipping lanes, etc., particularly in the notable absence of sea-use maps. This also allows for classification systems that are developed for particular application to the rohe pōtae (tribal territory) of iwi, but it may be inappropriate to apply elsewhere.
 
-### Primary land use
+#### Primary land use
 
 A justification should be given for the choice of primary land uses (e.g. land area, economic value, duration). Some classification systems are intended to capture only the primary land use for geographical entities, typically defined in economic terms. Some classification systems allow for the encoding of multiple uses, but in such a way that information about the primary land use is lost. For example, the ratings valuation rules ([LINZS30300](https://www.linz.govt.nz/resources/regulatory/rating-valuations-rules-2008-version-date-1-october-2010-linzs30300)) allow for ‘multiple use’ classes without the ability to encode the component uses.
 
 In contrast, data schemas for land-use classification systems produced under this framework should be designed in such a way that multiple uses can be recorded without loss of information (as with indeterminate ‘mixed’ classes, where the components are unspecified). This may be as a primary/secondary distinction, an enumeration, or some other form of attribution, but it must be possible in some fashion.
 
-### Provenance
+#### Provenance
 
 Source information (i.e. geographical scale, time/date, operator, and confidence) should be recorded. The value of land-use data is enhanced when information on provenance is available. This relates to the epistemological foundation of land-use data: how it is that we know the land use? Within the data schema of a classification system it must be possible to record provenance information, including, if applicable:
 
@@ -138,7 +170,13 @@ Source information (i.e. geographical scale, time/date, operator, and confidence
 
 ## Contribution
 
-TBD
+To contribute to the NZSLUC, including classification sytems defined under it like NZLUM, you can:
+- For general comment, questions or ideas:
+    - Raise or contribute to GitHub [Discussions](https://github.com/manaakiwhenua/nzsluc/discussions)
+- For specific, actionable suggestions:
+    - Raise or contribute to GitHub [Issues](https://github.com/manaakiwhenua/nzsluc/issues)
+- For involvement at a governance level and to directly influence the direction:
+    - Considering joining the [New Zealand Land-use Steering Group (NZLUSG)](https://nzlum.landcareresearch.co.nz/governance/nzlusg/), by emailing [[email protected]](mailto:[email protected])
 
 ## Glossary