diff --git a/docs-end-user.sidebars.yaml b/docs-end-user.sidebars.yaml new file mode 100644 index 00000000..05f47f79 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/end-user/adjust-project.md b/docs/end-user/adjust-project.md new file mode 100644 index 00000000..ab743300 --- /dev/null +++ b/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) diff --git a/docs/end-user/index.md b/docs/end-user/index.md new file mode 100644 index 00000000..3590ae2b --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/end-user/interact-with-api.md b/docs/end-user/interact-with-api.md new file mode 100644 index 00000000..f1251193 --- /dev/null +++ b/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) diff --git a/docs/end-user/interact-with-pages.md b/docs/end-user/interact-with-pages.md new file mode 100644 index 00000000..861cefa9 --- /dev/null +++ b/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) diff --git a/docs/end-user/navigate-project.md b/docs/end-user/navigate-project.md new file mode 100644 index 00000000..597a02e9 --- /dev/null +++ b/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 Tab key. +2. Press the Return or Enter 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) diff --git a/docs/end-user/use-search.md b/docs/end-user/use-search.md new file mode 100644 index 00000000..25170925 --- /dev/null +++ b/docs/end-user/use-search.md @@ -0,0 +1,79 @@ +# Search the project + +Projects come with search function to help you find the information you need. +Some projects can have AI-powered search you can prompt to get information distilled from your project's data. + +## Open search dialog + +{% tabs %} + + {% tab label="Desktop" %} + To open the search dialog on desktop devices, either: + + - In the top-right corner of the screen, click the **Search** field. + - Press `⌘ Cmd` + `K` or `Ctrl` + `K`. + + {% /tab %} + + {% tab label="Mobile" %} + + To open the search dialog on mobile devices: + + - In the top-right corner of the screen, select the magnifying glass icon. + + {% /tab %} + +{% /tabs %} + + +## Use AI search + +Some projects have AI-powered search enabled. +AI search saves the history of your conversations. + +To use AI-powered search: + +1. Open the Search dialog. +2. Click the **Search with AI** button. + +## Filter search results + +You can filter the results of your search to find the required information quicker. + +### Use filter categories + +Use search categories to restrict the results to the chosen category. +Projects come with two built-in search categories: **Documentation** and **API Reference**, but your project may have custom categories. +Categories are located under the search field. +After you enter a search query, each category button label displays the respective number of results. + +To filter search results using categories, click a category button. +In some cases, you can select multiple categories at the same time. +Other categories allow only a single selection. + +To reset category selection, click **All**. + +### Use advanced search filters + +Use advanced filters to narrow the search results and find relevant information faster. +This is especially useful when a project has a many or complex API description files. + +To display advanced filters: + +- Click the **Filters** icon in the top-right corner of the screen. + +Projects typically have the following filter options: + +- **Category**: display only the results that are included in selected categories. + These categories are the same as in the [main Search dialog](#use-filter-categories). +- **HTTP Method**: display only the results with the selected HTTP methods. +- **HTTP Path**: display only the results with the selected paths. +- **API Title**: display only the results from the selected description files. +- **API Version**: display only the results from the selected description file version. + +To clear all filters, in the top-right corner of **Advanced filters**, click **Reset filters**. + +## Resources + +- [Navigate the project](./navigate-project.md) +- Explore other ways you can interact with the [user interface](./index.md) diff --git a/docs/images/user-docs-icon.svg b/docs/images/user-docs-icon.svg new file mode 100644 index 00000000..6c3c424d --- /dev/null +++ b/docs/images/user-docs-icon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/docs/index.md b/docs/index.md index 8c7670a2..f259b3a1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,6 +67,13 @@ Ready to build something amazing? A tool to test API sequences described in Arazzo format. {% /card %} + {% card + title="End user docs" + to="end-user/index.md" + icon="images/user-docs-icon.svg" + %} + Guide to the project's user interface. + {% /card %} {% /cards %}