Update page structure

Author: Fannon

CHANGELOG.md

@@ -10,6 +10,12 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA
 
 ## [unreleased]
 
+### Changed
+
+- Changed the structure of the ORD page
+  - Details section removed, merged content either into spec itself (concepts) or new help area
+  - Moved FAQ into help, some detail article became FAQ articles
+
 ## [1.10.1]
 
 ### Added
@@ -189,9 +195,9 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA
 - Added clarification that an ORD Aggregator MUST bump `lastUpdated` if the provider didn't do it, but it detected a change.
 - Added explicit [Access Strategy](https://open-resource-discovery.github.io/specification/spec-extensions/access-strategies/) description for `open`, defining how local and global tenant headers can be optionally passed on.
 - Added new Detail Articles:
-  - [How To Adopt ORD as a Provider](https://open-resource-discovery.github.io/specification/details/articles/adopt-ord-as-provider) detail page
-  - [System Landscape Model](https://open-resource-discovery.github.io/specification/details/articles/system-landscape-model) detail page
-  - [Grouping and Bundling](https://open-resource-discovery.github.io/specification/details/articles/grouping-and-bundling) detail page
+  - [How To Adopt ORD as a Provider](https://open-resource-discovery.github.io/specification/help/faq/adopt-ord-as-provider) detail page
+  - [System Landscape Model](https://open-resource-discovery.github.io/specification/spec-v1/concepts/system-landscape-model) detail page
+  - [Grouping and Bundling](https://open-resource-discovery.github.io/specification/spec-v1/concepts/grouping-and-bundling) detail page
 
 ### Changed
 

dist/types/v1/Document.d.ts

@@ -1329,10 +1329,10 @@ export interface EventResourceDefinition {
     accessStrategies?: [AccessStrategy, ...AccessStrategy[]];
 }
 /**
- * An [**Entity Type**](../../details/articles/grouping-and-bundling#entity-type) describes either a business concept / term or an underlying conceptual model.
+ * An [**Entity Type**](../concepts/grouping-and-bundling#entity-type) describes either a business concept / term or an underlying conceptual model.
  * The same entity type can be exposed through one or multiple API and events resources.
  *
- * To learn more about the concept, see [Entity Type](../../details/articles/grouping-and-bundling#entity-type).
+ * To learn more about the concept, see [Entity Type](../concepts/grouping-and-bundling#entity-type).
  */
 export interface EntityType {
     /**
@@ -1791,9 +1791,9 @@ export interface CapabilityDefinition {
     accessStrategies?: [AccessStrategy, ...AccessStrategy[]];
 }
 /**
- * A [Data Product](../../details/articles/data-product) is a data set exposed for consumption outside the boundaries of the producing application via APIs and described by high quality metadata that can be accessed through the [ORD Aggregator](../../spec-v1/#ord-aggregator).
+ * A [Data Product](../concepts/data-product) is a data set exposed for consumption outside the boundaries of the producing application via APIs and described by high quality metadata that can be accessed through the [ORD Aggregator](../../spec-v1/#ord-aggregator).
  *
- * Please note that this concept is in beta, see [Data Product - Beta Status](../../details/articles/data-product#beta-status).
+ * Please note that this concept is in beta, see [Data Product - Beta Status](../concepts/data-product#beta-status).
  */
 export interface DataProduct {
     /**
@@ -2137,7 +2137,7 @@ export interface DataProductLink {
     url: string;
 }
 /**
- * An [Integration Dependency](../../details/articles/integration-dependency) states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose.
+ * An [Integration Dependency](../concepts/integration-dependency) states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose.
  * The purpose could be to enable a certain feature or integration scenario, but it could also be a mandatory prerequisite for the described system to work.
  *
  * The integration dependency includes a list of individual **aspects** that the integration consists of.
@@ -2155,7 +2155,7 @@ export interface DataProductLink {
  * An integration dependency is also not meant to describe a bigger process.
  * Instead it focuses on the technical necessaries to create an integration for one particular purpose.
  *
- * To learn more about the concept, see [Integration Dependency](../../details/articles/integration-dependency).
+ * To learn more about the concept, see [Integration Dependency](../concepts/integration-dependency).
  */
 export interface IntegrationDependency {
     /**
@@ -2530,7 +2530,7 @@ export interface Product {
     documentationLabels?: DocumentationLabels;
 }
 /**
- * A [**Package**](../../details/articles/grouping-and-bundling#package) organizes a set of related resources together, by publishing and catalog presentation concerns.
+ * A [**Package**](../concepts/grouping-and-bundling#package) organizes a set of related resources together, by publishing and catalog presentation concerns.
  *
  * The Package can also be used to indicate which products or vendors provided the packaged resources.
  * For partner or customer content, the package can indicate this via the `vendor` and `partOfProducts` assignments.
@@ -2543,7 +2543,7 @@ export interface Product {
  * A package does not have a `visibility` property.
  * Whether it is displayed is decided by the fact, whether it contains any visible resources according to the visibility role of the aggregator.
  *
- * To learn more about the concept and further guidance, see [Package](../../details/articles/grouping-and-bundling#package).
+ * To learn more about the concept and further guidance, see [Package](../concepts/grouping-and-bundling#package).
  */
 export interface Package {
     /**
@@ -2732,18 +2732,18 @@ export interface PackageLink {
     [k: string]: any | undefined;
 }
 /**
- * A [**Consumption Bundle**](../../details/articles/grouping-and-bundling#consumption-bundle) groups APIs and Events together that can be consumed with the credentials and auth mechanism.
+ * A [**Consumption Bundle**](../concepts/grouping-and-bundling#consumption-bundle) groups APIs and Events together that can be consumed with the credentials and auth mechanism.
  * Ideally it also includes instructions and details how to request access and credentials for resources.
  *
- * For more documentation and guidance how to correctly this correctly, see [Consumption Bundle details](../../details/articles/grouping-and-bundling#consumption-bundle).
+ * For more documentation and guidance how to correctly this correctly, see [Consumption Bundle details](../concepts/grouping-and-bundling#consumption-bundle).
  *
  * A consumption bundle SHOULD have at least one association with a resource (0..n). Avoid empty consumption bundles.
  * A consumption bundle MUST NOT contain APIs and Events that are NOT defined in the ORD document(s) returned
  * by the system instance that defines the consumption bundle.
  *
  * Please note that some ORD consumer use cases MAY depend on consumption bundle assignments to work with the resources.
  *
- * To learn more about the concept, see [Consumption Bundle](../../details/articles/grouping-and-bundling#consumption-bundle).
+ * To learn more about the concept, see [Consumption Bundle](../concepts/grouping-and-bundling#consumption-bundle).
  */
 export interface ConsumptionBundle {
     /**
@@ -2897,7 +2897,7 @@ export interface CredentialExchangeStrategy {
  * They express a "part of" relationship to the chosen group concept.
  * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
  *
- * To learn more about the concept, see [Group Concept Documentation](../../details/articles/grouping-and-bundling#Groups).
+ * To learn more about the concept, see [Group Concept Documentation](../concepts/grouping-and-bundling#Groups).
  */
 export interface Group {
     /**
@@ -2934,7 +2934,7 @@ export interface Group {
  *
  * Group Types can be defined centrally (ownership by authority namespace) or decentrally (defined by application / service itself).
  *
- * To learn more about the concept, see [Group Concept Documentation](../../details/articles/grouping-and-bundling#Groups).
+ * To learn more about the concept, see [Group Concept Documentation](../concepts/grouping-and-bundling#Groups).
  */
 export interface GroupType {
     /**

docs/details/articles/index.mdx

@@ -1,14 +1,9 @@
 ---
 title: Ecosystem
 id: ecosystem
+sidebar_position: 0
 ---
 
-# ORD Ecosystem
-
-A standard like ORD has the purpose to enable an ecosystem that provides mutual benefits for its participants.
-
-This page gives an overview of ORD related ecosystem support.
-
 ## SAP Ecosystem Support
 
 | ORD Providers                                                                                                                             | ORD Aggregators                                                              | ORD Consumers                                                                                                        | Frameworks                                                                         |
@@ -17,21 +12,6 @@ This page gives an overview of ORD related ecosystem support.
 | [SAP Marketing Cloud](https://help.sap.com/docs/SAP_MARKETING_CLOUD)                                                                      | [Unified Customer Landscape](../introduction.mdx#unified-customer-landscape) | [SAP Business Application Studio](https://www.sap.com/products/technology-platform/business-application-studio.html) | [SAP CAP Framework](https://github.com/cap-js/ORD)                                 |
 | [SAP Graph](https://help.sap.com/docs/graph)                                                                                              |                                                                              | [Kyma](https://help.sap.com/docs/btp/sap-business-technology-platform/kyma-environment) for side-by-side extensions  |                                                                                    |
 | [SAP ODM](https://blogs.sap.com/2023/09/12/harnessing-half-a-century-of-knowledge-saps-journey-of-enriching-apis-with-business-metadata/) |                                                                              |                                                                                                                      |                                                                                    |
+| [SAP Business Data Cloud](https://www.sap.com/products/data-cloud.html)                                                                   |                                                                              |                                                                                                                      |                                                                                    |
 
 > 🚤 List is incomplete. More in progress / planned.
-
-### Logo
-
-<div style={{"background": "#EEE", "padding": "6px", "border-radius": "6px"}}>
-
-![ORD Horizontal Logo (Color)](/img/logo/ORD_Horizontal_Color_Logo.svg "ORD Horizontal Logo (Color)")
-![ORD Icon Logo (Color)](/img/logo/ORD_Icon_Color_Logo.svg "ORD Horizontal Logo (Color)")
-![ORD Icon Logo (Black)](/img/logo/ORD_Icon_Black_Logo.svg "ORD Horizontal Logo (Color)")
-![ORD Icon Logo (White)](/img/logo/ORD_Icon_White_Logo.svg "ORD Horizontal Logo (Color)")
-![ORD Vertical Logo (Color)](/img/logo/ORD_Vertical_Color_Logo.svg "ORD Horizontal Logo (Color)")
-
-</div>
-
-#### Downloads:
-
-- [ORD Logos (zip file)](/img/logo/ord-logos.zip)

docs/details/index.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 2
-title: How To Adopt ORD (Provider)
+title: HowTo adopt as ORD Provider
 description: ORD Provider guide how to adopt ORD, depending on preconditions and requirements.
 ---
 

docs/ecosystem/index.mdx

@@ -1,6 +1,6 @@
 ---
-title: FAQ
-sidebar_position: 22
+title: FAQ 🙋
+sidebar_position: 10
 ---
 
 # FAQ
@@ -37,7 +37,7 @@ Currently, we're in discussion with other companies to form a community around t
 #### How long does it take for metadata changes to reflect in the Aggregators?
 
 This depends on the configuration and implementation of an ORD aggregator.
-The aggregation can be fully automated, but currently ORD has only defined a [pull transport](../spec-v1/index.md#pull-transport) mode, which relies on periodic fetching (similar as a search engine indexes the web). As a consequence, metadata changes need a while to be replicated.
+The aggregation can be fully automated, but currently ORD has only defined a [pull transport](../../spec-v1/index.md#pull-transport) mode, which relies on periodic fetching (similar as a search engine indexes the web). As a consequence, metadata changes need a while to be replicated.
 We're aware that some use-cases require faster metadata updates and the ORD spec is designed to support other transport modes (like push or event based), to make faster and more efficient replication possible.
 
 #### Q: Does ORD work for On-Premises Software?

…etails/articles/adopt-ord-as-provider.md docs/help/faq/adopt-ord-as-provider.mddocs/details/articles/adopt-ord-as-provider.md renamed to docs/help/faq/adopt-ord-as-provider.md docs/details/articles/adopt-ord-as-provider.md renamed to docs/help/faq/adopt-ord-as-provider.md

@@ -0,0 +1,11 @@
+---
+title: Help
+id: help
+sidebar_position: 0
+---
+
+# Help
+
+In this section you can find additional material to help you understand and use ORD.
+
+The [Primer](../introduction.mdx) is a good starting point.

docs/details/faq.md docs/help/faq/index.mddocs/details/faq.md renamed to docs/help/faq/index.md

@@ -0,0 +1,18 @@
+---
+title: Logos
+sidebar_position: 12
+---
+
+<div style={{"background": "#EEE", "padding": "6px", "border-radius": "6px"}}>
+
+![ORD Horizontal Logo (Color)](/img/logo/ORD_Horizontal_Color_Logo.svg "ORD Horizontal Logo (Color)")
+![ORD Icon Logo (Color)](/img/logo/ORD_Icon_Color_Logo.svg "ORD Horizontal Logo (Color)")
+![ORD Icon Logo (Black)](/img/logo/ORD_Icon_Black_Logo.svg "ORD Horizontal Logo (Color)")
+![ORD Icon Logo (White)](/img/logo/ORD_Icon_White_Logo.svg "ORD Horizontal Logo (Color)")
+![ORD Vertical Logo (Color)](/img/logo/ORD_Vertical_Color_Logo.svg "ORD Horizontal Logo (Color)")
+
+</div>
+
+#### Downloads
+
+- [ORD Logos (zip file)](/img/logo/ord-logos.zip)