more diataxis from api-specs-ssot & confluence to docs repos

README.md

@@ -62,7 +62,8 @@ Always update your fork to ensure you're working with the newest source files.
     ├── csv/                           # static files used in docs
     ├── images/                        # images and screenshots
     ├── json/                          # theme translation files
-    └── PO/                            
+    └── PO/
+├── diataxis-templates/                # templates for contributing to our documentation                             
 ├── docs                               # narrative documentation
     ├── api-docs/                      
     ├── bigcommerce-for-wordpress/     

diataxis-templates/README.md

@@ -0,0 +1,38 @@
+# Diataxis
+
+> This directory is for those who are interested in contributing to BigCommerce documentation.
+> It provides a starting point for how to organize the content you would like to contribute and where the content should live.
+> For more information on how to contribute, see the [Contributing](https://github.com/bigcommerce/docs?tab=readme-ov-file#contributing) section.
+
+## Purpose
+
+Diataxis is a framework that helps standardize the purpose and content of each page in our documentation.
+
+We use diataxis to help outline the types of content that make up our API Documentation.
+
+## Diataxis types
+
+There are four main types of documentation:
+
+- Overview: Introduces a topic to help users understand how a feature works at a high level.
+- Tutorials: Helps learners develop basic skills and understanding, preparing them to explore the rest of the product.
+- Guides: Outlines steps for completing a task in order. It helps users apply their existing skills to accomplish the task effectively.
+- Reference: Describe a product's behavior and usage, organized for quick skimming and selective use.
+
+There are many online sources that explain the difference between each Diataxis type in documentation.
+
+- https://diataxis.fr
+- https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework
+
+## Diataxis templates
+
+As a starting point, the following templates provide concrete examples of how you can document content for each Diataxis type.
+
+Some content in the Diataxis templates were based on the sources listed under [Diataxis types](#diataxis-types).
+
+Templates may vary depending on feature size.
+
+- [Overview](https://github.com/bigcommerce/docs/tree/main/diataxis-templates/overview.mdx)
+- [Tutorial](https://github.com/bigcommerce/docs/tree/main/diataxis-templates/tutorial.mdx)
+- [Guide](https://github.com/bigcommerce/docs/tree/main/diataxis-templates/guide.mdx)
+- [API Reference](https://github.com/bigcommerce/docs/tree/main/diataxis-templates/api-reference)

diataxis-templates/api-reference/api-reference.mdx

@@ -0,0 +1,69 @@
+#  Reference
+
+The structure for a reference depends on the reference type; there is no universal template. 
+
+However, references contain common elements, including product descriptions.
+
+This article explains common elements within references and provides templates for these elements.
+
+## Descriptions 
+
+To see the descriptions you need to provide, see `checklist.mdx`.
+
+> Note: In a description, add links to articles for explanation and/or context. If there is no link to an existing API Doc, use a link to a KB article. 
+
+### Overall features or endpoints 
+
+State the following in a description for endpoints or overall features: 
+- Feature’s purpose and capabilities (high-level)
+- Limitations or API behavior (may include in a field's description instead)
+
+| Template | Example |
+| - | - |
+| **Purpose and capabilities** | | 
+| This API allows you to... | This API allows you to manage newsletter and marketing email subscriptions on the storefront. | 
+| You must use a. You must not apply b unless c. Never d. | Use this endpoint only when you do not know absolute quantities. |
+| **Limitations or Behaviors** | |
+| The limit for x is y. | The maximum number of metafields allowed on each product, category, variant, or brand is 250. |
+|                       | Returns up to a maximum of 250 addresses. If a limit isn’t provided, up to 50 addresses are returned by default. |
+| The responses sort by... | Default sorting is by customer ID, from lowest to highest. |
+
+### Fields
+
+
+State the following in a description for a field:
+- What the field is or does
+- When a field applies
+- How the field works
+
+
+The following table has templates and examples for descriptions.
+
+| Template | Example |
+| - | - |
+| **What the field is or does** | |
+| X for y when doing z | ID for the tax zone a store uses when subtracting store tax. |
+| The store derives the field from... | BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel. |
+| This setting determines... When enabled, x occurs. When disabled, y occurs. | This setting determines which tax zone a store uses to estimate tax for guest shoppers. When enabled, the store identifies a country-level tax zone based on the geolocation of a guest shopper. |
+| This value is the same as, or must match... | This is the same email that is used in the billing address. |
+|                                             | This code should match the exemption codes provided by the third-party integration. |
+| | |
+| **When does the field apply** | |
+| The setting applies only if a merchant does x, you disable `example_field`, or... | This setting applies only if a merchant enters tax-inclusive prices. |
+|                                                                                   | Only applies to non-transactional currencies. |
+| These calculations are relevant for... | These calculations are relevant for tax pricing and tax quotations that use basic tax. |
+| The store uses this value when... | The store uses `default_currency` on the storefront when it cannot use other currencies. |
+| | |
+| **How the field works** | |
+| The store can only use the xyz you configure in abc. | The store can only match the tax zones you configure to the guest shopper's geolocation. |
+| This value includes or excludes x, depending on y. | This value can include or exclude tax, depending on the store setup. |
+| Value must be in the format... | Returns as an integer. Dollar and percentage discounts return without symbols. For example, $3 returns as 3 while 5% will return as 5. |
+|                                | Provide the value in the store’s default currency. |
+| This value is based on x and y. | Default value for this field is based on the channel type and platform combination. |
+| If the value is x, that means... | A UUID that is different from the active Theme Configuration UUID indicates that some changes have been saved in the control panel Theme Editor, but not yet published. |  
+| The store can use this field to... | The store can use this optional field to override the product name in the Catalog. |
+| | |
+| **How field relates to other API fields | |
+| Retrieve the field from x endpoint | Retrieve custom fields from the Get Form Fields endpoint. |
+
+

diataxis-templates/api-reference/checklist.mdx

@@ -0,0 +1,54 @@
+# API Reference Components
+
+This page provides a checklist for REST and GraphQL API references.
+
+> Notes: 
+> The checklists ask for descriptions. For information on how to write these, see `reference.mdx`.
+> When providing example requests and responses, it is best practice to demonstrate _main_ use cases.
+
+## REST API reference
+
+For each API endpoint, include the following at a minimum:
+
+- [ ] Description for the overall endpoint
+- [ ] Authentication method (OAuth scopes, etc)
+- [ ] Server URL
+- [ ] Path 
+- [ ] Method (GET, POST, PUT, DELETE) + Overall description for each method
+- [ ] Request and request body schema
+- [ ] Request and request body examples. State the example's use case in the title.
+- [ ] Type for each property (string, integer, etc)
+- [ ] Description for each property
+- [ ] Tag for each method, used to group methods together
+- [ ] API Status Codes (code, message, meaning) 
+- [ ] Subscription levels (Enterprise, Pro plans, etc)
+- [ ] Rate limits for each subscription level
+
+If applicable, include the following:
+
+- [ ] Usage notes
+- [ ] Path & query parameters
+- [ ] Default & min/max values
+- [ ] Required flags
+- [ ] Enum values (+ descriptions)
+- [ ] Format
+
+> Note: OAS3.0 files don't support descriptions for enum values. Add descriptions for enum values inside the description for the field.
+
+You may need to add additional information to resolve linting errors, for example, global tags and operation IDs.
+
+Consult surrounding or other endpoint files for conventions.
+
+## GraphQL APIs reference
+
+Reference documentation for GraphQL APIs are introspected from the code base. 
+
+This includes example requests and responses, which are autogenerated from code bases.
+
+The introspected reference for a GraphQL API should contain the following:
+
+- [ ] Queries (+ description)
+- [ ] Mutations (+ description)
+- [ ] Types, including their fields & arguments (+ descriptions)
+- [ ] Request examples
+- [ ] Response examples

diataxis-templates/guide.mdx

@@ -0,0 +1,156 @@
+# How to (task here)
+
+[Draft an intro here.]
+
+The introduction consists of 2-3 sentences to orient the reader:
+1. Provide brief context to explain why the user would want to accomplish the task in the guide. Note that smaller features may not have separate overview page. In this case, briefly describe the background, feature, and use cases.
+2. State the task that the guide accomplishes. The task should be specific, not open-ended.
+3. (If applicable) Add images, graphics, or diagrams describing the guide's tasks.
+
+[Example 1: Developers can build apps that can be installed on BigCommerce stores. Single-click apps are the recommended app type. In this quick start, you will create a single-click app using Node.js (Building Apps Quick Start).]
+
+[Example 2: Buy Online, Pick up in Store allows shoppers to purchase online and pick up in store. The solutions at BigCommerce are primarily API-driven. This guide walks you through the steps on how to create customized Buy Online, Pick up in Store solutions for merchants and shoppers (BOPIS End-to-End Guide).]
+
+## Prerequisites
+
+State what a user needs to do the guide, which may include:
+- Environment to use
+- Authentication (any tokens, OAuth scopes, etc)
+- Any prior knowledge or skills required for completing the guide
+- A starting point, what they should have configured
+
+Example 1: To complete the guide, you will need the following:
+- [BigCommerce sandbox store](https://start.bigcommerce.com/developer-sandbox/) (required to develop and test apps)
+- [Developer Portal Account](https://login.bigcommerce.com/login) (required to register apps)
+- Experience using npm
+- The most recent LTS version of [Node.js](https://nodejs.org/en) and its highest corresponding npm version
+
+Example 2: This guide assumes the merchant has the following configured:
+- A functioning BigCommerce store.
+- Store settings, including Catalog, Payments, Tax, and Order Fulfillment
+- A storefront that uses a custom checkout, such as…
+- A store-level API Account that contains the following OAuth Scopes…
+
+## Steps
+
+**(Option 1) Getting Started Guides**
+
+List step by step actions you need to take. Do the following for each step, as needed:
+1. State what, where, and/or how to perform the steps. 
+2. Add links to more detailed explanation.
+3. Include checks, especially for special cases. 
+4. Provide guidance on how to deal with unexpected possibilities.
+5. Best practices
+
+Steps may depend on the specific scenario and what users have available. Steps can be adaptable for real-world scenarios. 
+
+The following template has some examples. Fill in the rest of the template for your guide. Add example code, requests, and/or responses as needed.
+
+**Step 1** 
+1. Step: If you want x, do y. To achieve w, do z. If xyz happens, then...
+2. Link(s): For more info, see the article... 
+3. Checks: If you are using x, perform or check the following...  
+4. Other possibilities: For version y, you may find... in which case, do z...
+5. Best practices: It is best practice to... We recommend using...
+
+**Step 2** 
+1. Step: Navigate to the root directory of your project and install npm packages using `npm install`.
+2. Link(s): For more info on Checkout, see Checkout Overview.
+3. Checks: Open your browser and navigate to `http://127.0.0.1:8080/` to confirm the dev server is running. You should see content from `build/`.
+4. Other possibilities: When the shopper is signed in, use the `https://{{store-url}}/login/token/{{token}}` URL as the url option for embedCheckout. For unauthenticated shoppers, use the `embedded_checkout_url` as the url option instead.
+5. Best practices: It is best practice to include a version number in the Script URL field. 
+
+**Step 3** 
+1. Step: 
+2. Link(s):  
+3. Checks:  
+4. Other possibilities: 
+5. Best practices: 
+
+**Step 4** 
+1. Step:
+2. Link(s):  
+3. Checks: 
+4. Other possibilities: 
+
+
+
+**(Option 2) API Guides**
+
+API guides typically show how to manage the store or storefront using example requests and responses. 
+
+Provide an example request and response for each method that an endpoint uses. For example, if the endpoint has POST, PUT, GET, and DELETE methods, provide an example request and response for each. 
+
+For each example request in an API Guide, perform the following:
+1. State what the example request accomplishes and any caveats for the example.
+2. Add a link to the API reference endpoint. 
+3. Provide a code example for the request headers and body. Request headers show the HTTP method and URL. 
+4. Provide a code example for the response body.
+
+The following template has an example. Fill in the rest of the template with your example requests and responses.
+
+**Example 1**
+1. Description: View aggregate inventory information for a product, across all locations that stock it. Send a request to the Get inventory at locations endpoint. The following example filters by variant_id.
+2. Link to API Reference endpoint: Get inventory at locations, https://developer.bigcommerce.com/docs/rest-management/inventory/items#get-inventory-at-locations
+3. Request:
+
+  ```
+  GET https://api.bigcommerce.com/stores/{store_hash}/v3/inventory/items?variant_id=123
+  X-Auth-Token: {{access_token}}
+  Accept: application/json
+  ```
+
+4. Response:
+
+  ```
+  {
+    "data": [
+      {
+        "identity": {
+          "product_id": 123
+        },
+        "locations": [
+          {
+            "location_id": 1,
+            "location_code": "BC-LOCATION-1",
+            "location_name": "Default location",
+            "available_to_sell": 10,
+            "total_inventory_onhand": 11,
+            "location_enabled": true,
+            "settings": {
+              "safety_stock": 1,
+              "is_in_stock": true,
+              "warning_level": 1
+            }
+          }
+        ]
+      }
+    ],
+    "meta": {}
+  }
+  ```
+
+
+**Example 2**
+1. Description: 
+2. Link to API Reference endpoint: 
+3. Request:
+4. Response:
+
+
+**Example 3**
+1. Description: 
+2. Link to API Reference endpoint: 
+3. Request:
+4. Response:
+
+
+
+
+## FAQs
+
+For information on how to create a FAQ, see the Overview-FAQ section. 
+
+## Resources
+
+Provide all the links used in the guide.