docs(project): add end-user section to website and navigation docs

docs-end-user.sidebars.yaml

@@ -0,0 +1,15 @@
+- label: ← Back to Docs
+  href: /docs
+- separatorLine: true
+- page: docs/end-user/index.md
+  label: User interface overview
+- page: docs/end-user/navigate-project.md
+  label: Navigate a project
+- page: docs/end-user/adjust-project.md
+  label: Adjust a project
+- page: docs/end-user/use-search.md
+  label: Search a project
+- page: docs/end-user/interact-with-pages.md
+  label: Interact with pages
+- page: docs/end-user/interact-with-api.md
+  label: Interact with API documentation

docs/end-user/adjust-project.md

@@ -0,0 +1,57 @@
+# Adjust the project
+
+Projects include options you can use to make them suit your preferences.
+You can change the color mode, the language, or hide the sidebar.
+
+## Change the color mode
+
+You can change the color mode of the project to your preferences.
+Projects usually have light and dark color modes, but may include more.
+Typically, your project matches the color mode of your operating system.
+
+To change the project's color mode:
+
+- In the top-right corner of the screen, click the sun or the moon icon.
+
+The project toggles to the next color mode.
+
+## Change the language
+
+Projects can have content in multiple languages.
+If available, the project loads in the same language as your browser.
+Otherwise, it uses its default language.
+
+{% tabs %}
+
+  {% tab label="Desktop" %}
+    To change the project's language on desktop devices:
+
+    1. In the top-right corner of the screen, click the globe icon.
+    2. From the drop-down list, select a language.
+
+    The project now displays your chosen language.
+  {% /tab %}
+
+  {% tab label="Mobile" %}
+    To change the project's language on mobile devices:
+
+    1. Select the **Menu** icon in the top-right corner of the screen.
+    2. At the bottom of the menu, a language from the drop-down list.
+
+    The project now displays your chosen language.
+  {% /tab %}
+
+{% /tabs %}
+
+## Hide the sidebar
+
+You can hide your project's sidebar to make the pages better fit smaller screens.
+
+To hide the sidebar:
+
+- In the bottom-right corner of the sidebar, click the **Hide sidebar** button.
+
+## Resources
+
+- [Navigate the project](./navigate-project.md)
+- Explore other ways you can interact with the [user interface](./index.md)

docs/end-user/index.md

@@ -0,0 +1,12 @@
+# User interface overview
+
+Published projects contain various methods to navigate, search and interact with their content.
+These pages provide an overview of user interface elements and information how to use them.
+
+Explore the following pages to learn more about the projects' user interface:
+
+- [Navigate a project](./navigate-project.md)
+- [Adjust a project](./adjust-project.md)
+- [Search a project](./use-search.md)
+- [Interact with pages](./interact-with-pages.md)
+- [Interact with API documentation](./interact-with-api.md)

docs/end-user/interact-with-api.md

@@ -0,0 +1,109 @@
+# Interact with API documentation
+
+Projects render API description files in YAML or JSON format into human-readable API documentation.
+API documentation typically consists of:
+- a metadata page that displays the information on API version, description, security, and servers
+-  pages that describe individual operations
+API documentation can also have additional content independent of the description file, like quick start guides, security guides, or changelogs.
+
+Both the metadata page, and the operations page have multiple interface elements that help you perform your tasks.
+
+## Download API description file
+
+The project's API description files are available in both YAML and JSON formats.
+
+To download an API description file:
+
+1. Navigate to an API's metadata page.
+2. In the **Download API description** section next to your preferred format, click the **Download** icon.
+
+The file is downloaded to your machine.
+
+## Copy server URL
+
+The API's metadata page lists servers available to run the APIs operations.
+
+To copy a server's URL:
+
+- On an API's metadata page, in the **Servers** section, next to your preferred server, click the **Copy** icon.
+
+You can now paste the server URL into another application.
+
+## Change code sample server URL
+
+Each operation has a code sample you can use to test the API, or copy and paste the request into another application.
+
+To change the server URL:
+
+- On an operation's page, in the code sample's top-left corner, select a server from the drop-down list.
+
+The selected server is now displayed in the code sample.
+
+## Change code sample language
+
+API operation pages generate code samples for operations in one of several programming languages.
+You can select a language for all APIs in your project, or change it for a single operation.
+
+### Change code sample language globally
+
+To change the language of code samples globally:
+
+- On an API's metadata page, in the **Languages** box, select a language for the code samples.
+
+The code samples are now displayed in your chosen language for all APIs.
+
+### Change code sample language for a single operation
+
+To change the language of a single operation:
+
+- On an operation's page, in the code sample's top-right corner, select a language from the drop-down list.
+
+The code sample is now displayed in your chosen language.
+
+## Copy a code sample
+
+You can one-click copy code samples from API operation pages to use in your work.
+This function is especially useful with long code fragments.
+
+To copy a code sample:
+
+- In the top-right corner of the code sample, click the copy icon.
+
+You can now paste the code into another application.
+
+## Report an issue in a code sample
+
+If you see an error or an inconsistency in a code sample, you can report it to the project's owner.
+
+To to report a problem with a code sample:
+
+- In the top-right corner of the code sample, click the exclamation mark icon.
+- Describe the issue.
+- Click **Send**.
+
+Your message is sent to the organization that owns the project.
+
+## Provide feedback for an API operation
+
+You can send feedback for each operation
+A project can have different types of feedback forms:
+
+- thumbs up or down icons
+- mood icons: satisfied, neutral or unsatisfied
+- a rating in the form of icons, typically from 1 to 5 stars
+- a numerical scale, typically between 1 and 10
+- a comment
+
+After you interact with a form (except the comment form), a text field is displayed.
+In this field, you can add more details to your feedback.
+
+If you are logged in your project, your email address is automatically added to the feedback content.
+The owners of the project can use the address to follow-up with you on your comment.
+If are not logged in, or the project does not have login enabled, an optional **Email** field is displayed.
+
+After you click **Send**, your feedback is submitted.
+
+## Resources
+
+- [Interact with pages](./interact-with-pages.md)
+- Explore other ways you can interact with the [user interface](./index.md)

docs/end-user/interact-with-pages.md

@@ -0,0 +1,51 @@
+# Interact with pages
+
+Project pages have interactive elements you can use to provide feedback or copy code snippet content.
+
+## Provide feedback for a page
+
+You can give your feedback for each
+A project can have different types of feedback forms:
+
+- thumbs up or down icons
+- mood icons, typically satisfied, neutral or unsatisfied
+- a rating in the form of icons, typically from 1 to 5 stars
+- a numerical scale, typically between 1 and 10
+- a comment
+
+After you interact with a form (except the comment form), a text field is displayed.
+In this field, you can add more details to your feedback.
+
+If you are logged in a project, your email address is automatically added to the feedback content.
+The owners of the project can use the address to follow-up with you on your comment.
+If are not logged in, or the project does not have login enabled, an optional **Email** field is displayed.
+
+After you click **Send**, your feedback is submitted.
+
+## Copy code sample
+
+You can one-click copy code samples from the project page to use in your work.
+This function is especially useful with long code fragments.
+
+To copy a code sample:
+
+- In the top-right corner of the code sample, click the copy icon.
+
+You can now paste the code into another application.
+
+## Report an issue in a code sample
+
+If you see an error or an inconsistency in a code sample, you can report it to the project's owner.
+
+To to report a problem with a code sample:
+
+- In the top-right corner of the code sample, click the exclamation mark icon.
+- Describe the issue.
+- Click **Send**.
+
+Your message is sent to the organization that owns the project.
+
+## Resources
+
+- [Interact with API documentation](./interact-with-api.md)
+- Explore other ways you can interact with the [user interface](./index.md)

docs/end-user/navigate-project.md

@@ -0,0 +1,135 @@
+# Navigate the project
+
+The interface of a project has various elements you can use to navigate the project's contents.
+Some of these elements might have been customized or disabled in your project.
+
+## Skip to content
+
+You can jump directly to the main content of a project's page, skipping navigation elements and auxiliary information.
+
+To skip to the page's main content:
+
+1. After navigating to a page, press the <kbd>Tab</kbd> key.
+2. Press the <kbd>Return</kbd> or <kbd>Enter</kbd> key, or click the **Skip to content** button.
+
+The page content scrolls so that the first heading is at the top of the page.
+
+## Use the table of contents
+
+The table of contents (TOC) is displayed on the right side of the page and indicates your current position.
+You can click any item on the TOC to jump to that heading.
+
+## Navigate project pages
+
+Projects have multiple elements you can use to navigate its content.
+Depending on your device type (or screen size), the location and look of these elements can differ.
+
+### Navigation bar
+
+The navigation bar (navbar) contains links to major parts of the project.
+
+{% tabs %}
+
+  {% tab label="Desktop" %}
+    On desktop devices, the navbar is located at the top of the screen.
+    Some navbar items may contain a drop-down list of links.
+    This list expands when you hover your mouse over a navbar item.
+    Some projects may have [multiple products](#switch-between-products) that are displayed when you hover over the **Products** item.
+  {% /tab %}
+
+  {% tab label="Mobile" %}
+    To access the navbar on mobile devices:
+    - Select the **Menu** icon in the top-right corner of the screen and then select **Main menu**.
+
+    The contents of the menu change to represent the structure in the navbar.
+
+    Navbar items with nested links have a downward-facing arrow next to them.
+    To expand the list, select the arrow.
+    Projects with [multiple products](#switch-between-products) list them under the **Products** heading.
+  {% /tab %}
+
+{% /tabs %}
+
+### Sidebar
+
+The sidebar represents the structure and the hierarchy of pages in a project.
+A project can have a single sidebar with links to all pages, or a main sidebar with additional sidebars for different sections of the project's content.
+
+{% tabs %}
+  {% tab label="Desktop" %}
+    On desktop devices, the sidebar is located on the left of the page.
+  {% /tab %}
+  {% tab label="Mobile" %}
+    To access the sidebar on mobile devices:
+    - In the top-right corner of the screen, select the **Menu** icon.
+
+    The contents of the menu represent the structure of the sidebar.
+  {% /tab %}
+{% /tabs %}
+
+### Breadcrumbs
+
+Breadcrumbs are a series of links that are displayed above the main content of a page.
+The links are available only on pages that have at least one level of nesting in the sidebar.
+The order of breadcrumb links typically reflects the hierarchy in the sidebar: from the top-level page of the project to the currently displayed page.
+
+### Navigation buttons
+
+You can also use the navigation buttons located below the main content of the page.
+These buttons typically open the next page or the previous page in the order in the sidebar.
+Some projects may have a custom order for the navigation buttons to guide users through related content.
+
+## Switch between products
+
+A project can have multiple products represented by distinct portions of content.
+Products often have individual sidebars or other navigation elements, and their own visual style.
+
+{% tabs %}
+  {% tab label="Desktop" %}
+    On desktop devices, if a project has multiple products, the navbar includes a **Products** item that has a downward-facing arrow next to it.
+
+    To switch between products on desktop devices:
+
+    1. In the navbar, hover your mouse over **Products**.
+    2. Select an item from the drop-down list.
+
+    The content of the selected product loads and the label of the **Products** navbar item changes to the name of the selected product.
+  {% /tab %}
+  {% tab label="Mobile" %}
+    To switch between products on mobile devices:
+
+    1. Select the **Menu** icon in the top-right corner of the screen and then select **Main menu**.
+    2. Under the **Products** heading, select a link.
+
+    The content of the selected product loads.
+  {% /tab %}
+{% /tabs %}
+
+## Switch between versions of a page
+
+Pages that have multiple versions in a project display a version picker above the sidebar.
+When you first access a page, the page's latest or default version is displayed.
+
+{% tabs %}
+  {% tab label="Desktop" %}
+    To switch between page versions on desktop devices:
+
+    - Above the sidebar, click the **Versions** dropdown and select a version from the drop-down list.
+
+    The page's content changes to reflect the selected version.
+  {% /tab %}
+  {% tab label="Mobile" %}
+    To switch between page versions on a mobile device:
+
+    1. Select the **Menu** icon in the top-right corner of the screen.
+    2. Under the **Version** heading, select a version from the drop-down list.
+
+    The page's content changes to reflect the selected version.
+  {% /tab %}
+{% /tabs %}
+
+## Resources
+
+- [Adjust the project](./adjust-project.md)
+- [Search the project](./use-search.md)
+- Explore other ways you can interact with the [user interface](./index.md)