diff --git a/README.md b/README.md index 8fd87d532..0afbf251e 100644 --- a/README.md +++ b/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/ diff --git a/diataxis-templates/README.md b/diataxis-templates/README.md new file mode 100644 index 000000000..577803480 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/diataxis-templates/api-reference/api-reference.mdx b/diataxis-templates/api-reference/api-reference.mdx new file mode 100644 index 000000000..a62b29d33 --- /dev/null +++ b/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. | + + diff --git a/diataxis-templates/api-reference/checklist.mdx b/diataxis-templates/api-reference/checklist.mdx new file mode 100644 index 000000000..20c5d1313 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/diataxis-templates/guide.mdx b/diataxis-templates/guide.mdx new file mode 100644 index 000000000..bff5d564f --- /dev/null +++ b/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. \ No newline at end of file diff --git a/diataxis-templates/overview.mdx b/diataxis-templates/overview.mdx new file mode 100644 index 000000000..d91312ae3 --- /dev/null +++ b/diataxis-templates/overview.mdx @@ -0,0 +1,175 @@ +# Overview for (topic) + +State purpose of the overview. + +[Example 1: This overview explains the core features that power multi-storefront, multi-channel stores.] + +[Example 2: This overview introduces BigCommerce's Orders V2 and Orders V3 REST API resources.] + +## Introduction + +1. Provide background + + State the problem or gap that the feature addresses. Provide context to orient the reader. When you describe the situation, consider who, what, where, when, and/or why. + + [Example: Some merchants want to sell their products in different places. They may want to maintain multiple website-based ecommerce storefronts, or sell products from their store's catalog on other channels, such as Amazon, eBay, and in-person POS (point-of-sale) systems.] + +2. Introduce the feature + + Describe the feature and how it fills in the problem or gap stated previously. Explain why the feature is useful. Explain how the feature works at the high level. + + [Example: Multi-storefront capabilities extend the reach of BigCommerce stores. Merchants can maintain multiple websites, on which they can configure and customize the look, feel, pricing, and organization of the shopping experience to support multiple distinct brands or sales goals.] + +3. State target audience(s) + + [Example: Merchants that support cross-border transactions may benefit from this feature.] + + +## Concepts & Terminology + + +List all concepts that a feature or API uses. Include basic terms, those that are part of ecommerce culture, and those you were not familiar with before joining BigCommerce. + +For each concept or term: +1. Define the term and provide explanation. +2. (If applicable) List the components of a term. Provide a definition for each component. +3. Connect concepts to the overall feature and/or use case. This creates connections for the reader. + +To ensure clarity, explain acronyms once and then use the acronym consistently throughout your document. + +The following template has an example. Fill in the rest of the template for your guide. + +**Term 1: Channel** +1. Definition & Explanation: A channel is a place where a merchant's store sells products. Storefront websites, marketplaces like Amazon and eBay, point-of-sale systems, and marketing feeds are all sales channels. A custom channel may not fit into any one of these types... +2. (If applicable) Components: A channel is defined by a name, type, and platform. A type is... A platform is... +3. Context: Channels can help to organize a merchant's complex business by allowing them to sell to many customers in many places from a single catalog in one BigCommerce store. + +**Term 2** +1. Definition & explanation: +2. (If applicable) Components: +3. Context: + +**Term 2** +1. Definition & explanation: +2. (If applicable) Components: +3. Context: + +**Term 2** +1. Definition & explanation: +2. (If applicable) Components: +3. Context: + + +## Use Cases + +APIs and features are designed so that they can be used under specific situations. Describe the specific situations in which a reader would benefit from the feature. + +1. List specific tasks that you can perform with the API + + [Example: Track inventory across multiple locations.] + +2. State specific situations in which you should use this API (or endpoint) in favor of another. + + [Example 1: Use the Inventory API as the default method for updating inventory. Absolute adjustments are batched, making them more resource friendly than the Catalog API.] + + [Example 2: Use relative adjustments only when you do not know absolute quantities. For example, making order-related inventory changes through a third-party may require relative adjustments. Otherwise, use absolute adjustments for updating inventory.] + +## Design Context + +Provide context to explain why a product is a certain way. + +1. Technical constraints: Discuss constraints that affected the product design. + + [Example: To prevent excessive loads, the API sets a complexity limit.] + +2. API design: The design of an API reflects the use cases. Explaining the API design helps readers understand how to use the API in their situation. + + [Example use case: Tax providers may sometimes need multiple inputs that can vary between different types of product. For example, for products with alcohol, the alcohol percentage and the volume sold affect alcohol taxes.] + + [Example Explanation for the API Design: Using Tax Properties, merchants can provide both pieces of information to tax providers. After you create tax properties, the API allows you to attach multiple tax properties to a product. This design also allows you to have tax properties that vary between different products; you choose which properties to attach to a product.] + +## Additional Information + +Depending on the feature, you may need to include additional information. + +1. Details: Elaborate on various aspects of the feature. Provide alternatives. Explain behaviors, or why something does what it does. + + [Example: When you configure multiple currencies, BigCommerce will convert the catalog default currency price of items into the selected non-default currency on the storefront. It does not change the default catalog pricing of products.] + + [Example: The reason for x is because historically, y was only available for...W is used in favor of z because...Some users prefer w because z. This can be a good approach, but...] + + [Example: An x in system y is analogous to a w in system z. Thus, an x interacts with a y as follows. However...] + +2. Visuals: Diagrams that clarify. + + [Example: Diagram for MSF explaining stores, channels, sites.] + +3. Relationships: Connect concepts to other features, approaches, or APIs. + + [Example: V3 Improvements section comparing Catalog V2 and V3 APIs] + +4. Usage notes: Add details about how to use a feature. + + [Example 1: Deleting a coupon using this endpoint will delete the coupon but not the attached promotion.] + + [Example 2: Once the order is paid, the cart is deleted.] + +5. Implications: Explore effects or outcomes. + + [Example: The Inventory API is not channel aware; inventory is shared across channels. Automated or bulk operations you perform with the Inventory API, as well as changes in stock level from a storefront order, will affect inventory available on all storefronts.] + +## Limitations, Supported & Unsupported features + +Provide a list for each of the following, if applicable: + +1. Platform or performance limitations + + [Example 1: Do not perform bulk operations using the Inventory API in parallel with bulk operations that use the Catalog or Orders APIs. Doing so may cause unpredictable, incorrect calculation results, as the Catalog and Orders APIs may force inventory calculations.] + + [Example 2: Wait to send new requests until the current request returns a 200 success status code.] + +2. Supported and unsupported features. + + [Example: Supported & Unsupported Features for Multi-Currency https://developer.bigcommerce.com/docs/store-operations/currencies#supported-and-unsupported-features] + +## FAQs + +- Include 5-10 questions that are asked by readers or pull highlights from the documentation. +- Questions should belong to a larger narrative. Goal-oriented questions should be fleshed out in a tutorial or guide, not listed under a FAQ. Avoid random questions; incorporate random details into the documentation. +- Each answer should be 2-3 sentence summaries. Include a link to the documentation topic, if any. + +The following template has an example. Fill in the rest of the template for your guide. + +**1. Good example question: Can I skip creating the quote and go straight to processing a refund?** + +[Example answer: It is possible to process a refund without creating a quote first. Quotes serve to make sure you are refunding to the correct payment provider in the correct amount.] + +**2. Bad example question: How do I create XYZ for my server?** + +[Example answer: The question should be fleshed out in a tutorial or guide, not included as a FAQ question.] + +**3. Question 3** + +Answer: + +**4. Question 4** + +Answer: + +**5. Question 5** + +Answer: + + + +## Resources + +At a minimum, links should include all links referenced in the doc and the following: + +- Guides & Tutorials + +- API reference endpoints + +- Support articles + +- External articles \ No newline at end of file diff --git a/diataxis-templates/tutorial.mdx b/diataxis-templates/tutorial.mdx new file mode 100644 index 000000000..3d696c290 --- /dev/null +++ b/diataxis-templates/tutorial.mdx @@ -0,0 +1,90 @@ +# Tutorial for (learning goal)  + +1. Provide brief context in 2-3 sentences. + + [Template: Developers can build x, which can be used for... This is beneficial for y...] + +2. Describe what you will accomplish. Provide a starting point and a conclusion. + + [Template: In this tutorial, you will...] + + [Example: In this tutorial you will build a simple website using Django and deploy it using Docker. Along the way you will use a cloud storage service for handling media files, and will configure your application to use it. (Diataxis.fr)] + +3. State learning goals + + [Template: By the end, you should be able to (general list of skills)...] + + [Example: By the end, you should know the basics of building and deploying a website...] + +## Prerequisites + +Define all tools and conditions mentioned in the tutorial; provide exactly what you need for the learning path. Environments that mimic real-life scenarios are sufficient. + + Template: This tutorial assumes you have the following: +- x +- y +- z + +Example: This tutorial assumes you have 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 + +Provide concrete steps. For each step: +1. Show what to do. Be explicit about how and where to do each step. +2. Keep minimal explanations. Link to more detailed explanation. +3. Set clear expectations. Show what will happen when you do it (correct answer). Ensure the learner immediately sees the effect, however small, of every action. +4. Provide clues to confirm learner is on the right track. Point out what the learner should encounter. + +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: First, do x. Now, do y. After y, do z. +2. (Optional) Minimal explanation: We must always do x before we do y because… (see Explanation for more details). +3. Output: The output should look something like this... +4. Clues: Notice that... Remember that... + +**Step 2** +1. Step: From your developer’s console, execute the following command to fetch checkout content. +2. (Optional) Minimal explanation: We’re using HTTPS because it’s more secure (Diataxis.fr). +3. Output: In the developer console, you will see the checkout object, for example... +4. Clues: In the following code snippet from the Cornerstone file templates/components/products/product-view.html, note the data tag named data‑cart‑item‑add. + +**Step 3** +1. Step: +2. (Optional) Minimal explanation: +3. Output: +4. Clues: + +**Step 4** +a. Step: +b. (Optional) Minimal explanation: +c. Output: +d. Clues: + +## Recap + +At the end of the tutorial, describe what the learner accomplished. + +Summarize key lessons and takeaways. + +[Template: You have built…] + +[Example: You have built a secure, three-layer hylomorphic stasis engine... (Diataxis.fr)] + +## Assessment + +Use questions or exercises to check understanding. + +## Next Steps + +Provide additional resources for more learning. + +Links should include the following at a minimum: +- Guides +- API reference endpoints +- KB support articles \ No newline at end of file