diff --git a/docs/en/changelog/changelog-test.md b/docs/en/changelog/changelog-test.md new file mode 100644 index 000000000..2597f210c --- /dev/null +++ b/docs/en/changelog/changelog-test.md @@ -0,0 +1,17 @@ +--- +title: 'Changelog test file' +id: changelog-test-file +status: PUBLISHED +createdAt: 2024-11-05T19:24:22.388Z +updatedAt: 2024-11-05T19:24:22.388Z +publishedAt: 2024-11-05T19:24:22.388Z +firstPublishedAt: 2024-11-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: changelog-test-file +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: changelog-test-file +--- + +This is a test file to check the connection between the documentation repository and the webpage repository. \ No newline at end of file diff --git a/docs/en/documentation/app-documentation.md b/docs/en/documentation/app-documentation.md new file mode 100644 index 000000000..6a567f924 --- /dev/null +++ b/docs/en/documentation/app-documentation.md @@ -0,0 +1,123 @@ +--- +title: 'App documentation' +id: edu0006 +status: PUBLISHED +createdAt: 2024-12-04T19:24:22.388Z +updatedAt: 2024-12-04T19:24:22.388Z +publishedAt: 2024-12-04T19:24:22.388Z +firstPublishedAt: 2024-12-04T19:24:22.388Z +contentType: trackArticle +productTeam: Education +slugEN: app-documentation +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: app-documentation +--- + +An App documentation guide helps users understand the [VTEX app](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-a-vtex-app), the installation, and the configuration processes. + +ℹ️ To add documentation in an app, you must use the [Docs builder](https://developers.vtex.com/docs/guides/vtex-io-documentation-docs-builder). The documentation is written in Markdown files, inside the app’s repository. By using the Docs builder, the documentation becomes publicly available at the [VTEX Developer Portal](https://developers.vtex.com/). + +In this guide, you will learn about the available template, general guidelines, and see examples of Onboarding articles. + +> ⚠️ This guide is part of the [App Store guidelines](https://developers.vtex.com/docs/guides/vtex-io-documentation-homologation-requirements-for-vtex-app-store) and one of the requirements to submit an app to the homologation process and [make it available in the App Store](https://developers.vtex.com/docs/guides/vtex-io-documentation-homologation-requirements-for-vtex-app-store). + +
+App documentation template + +```md +# {Insert the app's name} + +The `{insert app's name}` is responsible for `{app's purpose}` so you can `{job to be done}`. + +![insert-an-image-preview](/) + +## Before you begin + +You need to have `{insert what the user needs to have: an account in another platform, CLI, knowledge in another app, etc}`. + +If you do not have `{insert what the user needs to have and how to obtain it}`. + +## Installation + +1. [Install](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-installing-an-app) the `{insert app's name}` app in the desired VTEX account by running `vtex install {appVendor}.{appName}` in your terminal. +2. (Optional, for frontend apps) Open your store’s Store Theme app directory in your code editor. +3. (Optional, for frontend apps) Open your app's `manifest.json file` and add the `{insert app's name}` app under the `peerDependencies` field. + + + "peerDependencies": { + "vtex.{appName}": "{appVersion}" + } + + +4. (Optional, for frontend apps) Declare the `{insert app's name}` app in the desired template. For example: + + "store.home": { + "blocks": [ + + "{app-name}", + ] + }, + +*![insert-an-image-preview](/)* + +## Configuration + +Once you have installed the app, you can `{describe the app's configuration in the VTEX Admin as defined in the settingsSchema[https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest#settingsschema], for example}`. + +1. `First step`. +2. `Second step`. +3. `Third step`. + +## Customization (optional, for frontend apps) + +To apply CSS customizations to this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-using-css-handles-for-store-customization). + +| CSS Handles | +| ------------------ | +| csshandlesName | +| csshandlesName | +| csshandlesName | + +## How the app works (Optional) + +When the app requires user interaction beyond the Admin configuration. This section is recommended for [Admin apps](https://learn.vtex.com/docs/course-admin-lang-en). + +`{Detail what can be done with the app and show the steps to perform each operation.}` + +## Contributors + +Thanks go to these wonderful people: + +- `{insert the GitHub username}` + +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome. +``` +
+ +## General guidelines + +| **Topic** | **Description** | ✅ Do | ❌ Don’t | +| :---- | :---- | :---- | :---- | +| **Target audience** | Identify your readers. | Differentiate between developers and business users. | Assume a single audience. | +| **Learning objectives** | Define the user's takeaway. | Clearly state what users should learn. | Leave learning goals ambiguous. | +| **Title** | A clear and concise title. | Use the app name and a verb describing the learning objective. Capitalize the first letter of each word. | Include punctuation, version numbers, or the word "App". | +| **Introduction** | Briefly introduce the app and its benefits. | Summarize the app's purpose and user benefits. Include an image and callouts for important notes. | Focus solely on technical details. | +| **Before you begin (Optional)** | List requirements before installation. | Use clear bullet points or checklists. Utilize callouts if applicable. | Write lengthy paragraphs explaining prerequisites. | +| **Installation** | Provide a step-by-step guide with code snippets (if applicable) | Offer clear and concise steps. Enhance clarity with code snippets. | Skip steps or lack specific instructions. | +| **Configuration** | Guide users through configuring the app. | List all essential settings with detailed steps as defined in the [settingsSchema](https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest#settingsschema). | Omit configuration details. | +| **How it works** | (Optional) Detail the app functions and provideoffer steps for usingutilizing the app. | Use numbered lists for each operation, with clear and concise steps. Use images to illustrate the UI. | Skip steps or lack specific instructions. | +| **Customization** | (Optional) ProvideOffer steps for customizing the app. | Include [CSS handles](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-using-css-handles-for-store-customization) and a related table if applicable. Reference external documentation for CSS customization. | Ignore customization options. | +| **Contributors** | (Optional) Acknowledge contributors. | Follow the [All-Contributors specification](https://github.com/all-contributors/all-contributors). | Omit recognition of contributors. | +| **Callouts** | Highlight information using callouts. | Use the provided callout types (Information, Warning, Danger) with appropriate messages.: | Use generic text to highlight information. | + +## Examples of App documentation articles + +* [Breadcrumb](https://developers.vtex.com/docs/apps/vtex.breadcrumb) +* [SKU Selector](https://developers.vtex.com/docs/apps/vtex.store-components/skuselector) +* [Store Locator](https://developers.vtex.com/docs/apps/vtex.store-locator) +* [Store Sitemap](https://developers.vtex.com/docs/apps/vtex.store-sitemap) +* [Assembly Options](https://developers.vtex.com/docs/guides/assembly-options-app) +* [Installing Google Tag Manager](https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-google-tag-manager) +* [Live Shopping](https://developers.vtex.com/docs/apps/vtexventures.livestreaming) +* [Personal Shopper](https://developers.vtex.com/docs/apps/vtexventures.personal-shopper-free) +* [Pinterest app](https://developers.vtex.com/docs/apps/pinterestpartnerbr.pinterest@1.x) diff --git a/docs/en/documentation/best-practices-for-writing-documentation.md b/docs/en/documentation/best-practices-for-writing-documentation.md new file mode 100644 index 000000000..a55086293 --- /dev/null +++ b/docs/en/documentation/best-practices-for-writing-documentation.md @@ -0,0 +1,96 @@ +--- +title: "Best practices for writing documentation" +id: edu0001 +status: PUBLISHED +createdAt: 2024-12-03T19:24:22.388Z +updatedAt: 2025-01-27T12:00:00.388Z +publishedAt: 2024-12-03T19:24:22.388Z +firstPublishedAt: 2024-12-03T19:24:22.388Z +contentType: trackArticle +productTeam: Education +slugEN: best-practices-for-writing-documentation +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: best-practices-for-writing-documentation +--- + +At VTEX, our goal for documentation is to make everything as simple and clear as possible for users working with or interested in VTEX solutions. + +We welcome contributions to VTEX documentation and encourage you to help improve the user experience. There are several ways to contribute, depending on the documentation portal you're interested in and your preferred method. Check our [Contribution Guidelines](https://language-hub.netlify.app/docs/documentation/contribution-guidelines) for more information. + +Before contributing to the documentation, make sure to: + +- + +## Define the documentation structure + +Before you start writing, it’s important to understand your target audience and the specific goals of your documentation. To help you define the documentation objectives, answer the following questions: + +- What do you want users to achieve after reading your documentation? +- What are the essential tasks or concepts they need to understand? +- What additional information could enhance user understanding? + +### Identify the audience + +To help you define the audience, answer the following questions: + +- Who is the target audience for that information? +- What are they trying to do? + +At VTEX, we have the following audience as our documentation readers: + +| Audience type | Description | +| :------------ | :------------ | +| **Beginner** | New to ecommerce operations and VTEX, with little to no prior experience. Their main challenge is adapting to the platform and the ecommerce context. | +| **Operational** | Handles daily ecommerce tasks, such as SKU registration and promotion management. Familiar with the ecommerce context but may encounter problems that they can’t solve by themselves. | +| **Highly Technical** | Builds or integrates technical solutions with VTEX. They work on store implementations, app development with our solutions, and integrations with partner systems via VTEX APIs. This audience requires in-depth technical documentation that describes the characteristics of all our features and indicates how to address business needs. | + +### Checklist to define the documentation objectives + +To help you define the documentation context, see the checklist below: + +#### Audience + + +
+ +
+ +

+ +#### Learning Category + + +
+ +
+ +

+ +#### Learning Objective + + +
+ What should someone be able to do or understand after reading this article? Choose one or two tasks or concepts that the content will discuss. + Template example: + + ```md + "Create a guide on {add the guide’s purpose}. The guide should emphasize clarity, structure, and user-friendliness. It's intended for {add the guide’s audience}." + ``` + +## Documentation style guide + +This guideline is the VTEX interpretation of stylistics as a discipline and explains particular language choices when creating functional and technical content about our platform. + +### Style guide principles + +| Principle | Orientation | Usage | +| :--------- | :----------- | :----- | +| **Clarity and conciseness** |
  1. Use simple language and avoid jargon. Break down complex concepts into smaller, easier-to-understand steps.
  2. Use clear and informative headings and subheadings to guide readers through the documentation.
|
  1. Instead of *Utilize the API endpoint for product creation.* write, *Create a new product using the API.*
  2. Use headings like *Getting started*, *Instructions*, and *Advanced features*.
| +| **Consistency** | Maintain consistency in terminology, style, and formatting throughout the documentation. | Use the same terminology for similar concepts referring to the same subject/reader consistently from the beginning to the end of the text (example: *customer* instead of *client*, and stick to *you* instead of alternating with *user* or *member*). | +| **Completeness** | Make sure the documentation is both comprehensive and concise, covering all relevant topics with enough detail. | If you’re documenting a feature, include information on how to use it, common use cases, and potential troubleshooting steps. | +| **Usability** | Consider the user's perspective and write the documentation in a way that is easy to navigate and use. | Use clear headings, subheadings, and bullet points to organize the content. | +| **Logical flow** | Organize the content in a logical sequence that is easy to follow. | Start with an introduction, followed by detailed sections on specific topics. | +| **Media and code examples** | Use media such as diagrams, screenshots, and code examples to enhance understanding. | Use screenshots, diagrams, and code snippets to illustrate examples and ensure accuracy. *Tip:* Diagrams, like platform or product architecture diagrams, can help illustrate complex processes or relationships. | + +For more details about these principles, see the [style guide section](LINK). diff --git a/docs/en/documentation/contribution-guidelines.md b/docs/en/documentation/contribution-guidelines.md new file mode 100644 index 000000000..a36250d86 --- /dev/null +++ b/docs/en/documentation/contribution-guidelines.md @@ -0,0 +1,103 @@ +--- +title: 'Contribution Guidelines' +id: edu0002 +status: PUBLISHED +createdAt: 2024-12-03T19:24:22.388Z +updatedAt: 2024-12-03T19:24:22.388Z +publishedAt: 2024-12-03T19:24:22.388Z +firstPublishedAt: 2024-12-03T19:24:22.388Z +contentType: trackArticle +productTeam: Education +slugEN: contribution-guidelines +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: contribution-guidelines +--- + +Your help makes a huge difference in improving the VTEX documentation experience. There are several ways to contribute, depending on the documentation portal you're interested in and your preferred method. This guide outlines these ways you can help improve VTEX documentation: + +* [Feedback button](LINK) +* [Was this helpful?](LINK) +* [Suggest edits (GitHub)](LINK) +* [GitHub Issues](LINK) + +## Feedback button + +**Available at:** [Help Center](https://help.vtex.com/) and [Developer Portal](https://developers.vtex.com/) + +You can submit your feedback about any page in the documentation portals by clicking `Feedback` at the top corner of each portal. + +By clicking `Feedback`, a new browser window will open with a [form](LINK) for you to write with your feedback. Here’s the information you need to provide in the feedback form: + +* **Platform:** Select one of the following portals you would like to give feedback, [Help Center](https://help.vtex.com/), [Developer Portal](https://developers.vtex.com), or [VTEX Learning Center](https://learn.vtex.com/). +* **URL (optional):** If you want to give feedback for a specific page in one of the portals mentioned before, add the exact page URL, for example: `[https://developers.vtex.com/docs/guides/getting-started-with-storefront-solutions](https://developers.vtex.com/docs/guides/getting-started-with-storefront-solutions)`. +* **Feedback type:** Choose the type of feedback you want to give: + + +| Feedback type | Description | +| :---- | :---- | +| Comment | Leave a comment about the documentation. | +| Question | Describe any doubts you have regarding the documentation content. | +| Error | Report incorrect information on documentation content or if the page isn't available. | +| Improvement | Suggest improvements to the content. | + + +* **Feedback:** Describe your feedback based on the **Feedback type** you’ve chosen. +* **Suggestions (optional):** Add a suggestion to fix or improve the content. +* **Attachment (optional):** If you have additional files to share, such as screenshots, images, and spreadsheets, upload them to this section. +* **Follow-up:** If you want us to contact you about your feedback, select `Yes`. Add your name and email on the next page of the form so we can reach out to you. + +## Was this helpful? + +**Available at:** [Help Center](https://help.vtex.com/) and [Developer Portal](https://developers.vtex.com/) + +You can submit feedback about any page in the documentation portals by responding to the `Was this helpful?` option. + +![How to submit feedback](https://raw.githubusercontent.com/vtexdocs/language-hub-content/refs/heads/main/images/en/how-to-submit-feedback.gif) + +You can leave a comment about the page and why you found it helpful or not. Click `SEND FEEDBACK` to send your feedback. + +## Suggest edits (GitHub) + +**Available at:** [Help Center](https://help.vtex.com/) and [Developer Portal](https://developers.vtex.com/) + +You can contribute to any page in the documentation portals by clicking `Suggest edits (GitHub)`. + +![How to suggest edits](https://raw.githubusercontent.com/vtexdocs/language-hub-content/refs/heads/main/images/en/how-to-suggest-edits.gif) + +By clicking `Suggest edits (GitHub)`, a new browser window will open with the documentation repository page. Follow these steps to contribute using the `Suggest edits (GitHub)`: + +1. In the documentation repository page, edit the documentation file according to your suggestions. + + > ⚠️Make sure to apply your suggestions based on the [documentation guidelines](https://docs.google.com/document/d/1i4-us9j-V8b8u5FmFu1aG0l8TzZq5isL2nH2txyW--U/edit?usp=drive_link) and the [code of conduct](https://github.com/vtexdocs/dev-portal-content/blob/main/CODE_OF_CONDUCT.md) and maintain the documentation structure according to its [template](https://docs.google.com/document/d/1ZH2P2p6cBLcu94xaCMXpGn47NFTGHdssc7DRreoG5Fk/edit?usp=drive_link). + +2. Click `Commit changes…`. +3. In the **Propose changes** modal, complete the following: + + + + +| Field name | Description | +| :---- | :---- | +| Commit message | Write a short description of your commit, for example, `Fix typo`. | +| Extended description (Optional) | Write a description of your commit in more detail. | +| Create a new branch for this commit and start a pull request | Give a name for your branch so you can open a pull request, and the team can review your suggestions. | + +4. Once you have completed the modal, click `Propose changes`. +5. Create a pull request with your changes by completing the following: + + ![How to open a pull request](https://raw.githubusercontent.com/vtexdocs/language-hub-content/refs/heads/main/images/en/how-to-open-a-pull-request.png) + + + +| Field name | Description | +| :---- | :---- | +| Add a title | Add a title for your pull request by adding the type of change, the filename, and what you changed, for example, `Fix (customer-credit-integration-guide.md): Documentation typos`. | +| Add a description | Check the type(s) of change(s) you are proposing: New content, Improvement, Fix or Spelling and grammar accuracy. Also, feel free to provide more details in your description to help the team review your suggestion. | +| Reviewers | Click `Reviewers` and choose the group `vtexdocs/vtex-education`. | + +6. Click `Create pull request`. + +Once you have opened a pull request, our team will review your changes as soon as possible and follow up with you in the pull request comments. + +> ⚠️ Pull requests are a collaborative process. Your suggestions are valued, but approval is not guaranteed. Be open to feedback and discussion. diff --git a/docs/en/documentation/documentation-overview.md b/docs/en/documentation/documentation-overview.md new file mode 100644 index 000000000..2c8b59c01 --- /dev/null +++ b/docs/en/documentation/documentation-overview.md @@ -0,0 +1,63 @@ +--- +title: 'Product Documentation overview' +id: edu0003 +status: PUBLISHED +createdAt: 2024-12-03T19:24:22.388Z +updatedAt: 2025-01-27T11:55:00.388Z +publishedAt: 2024-12-03T19:24:22.388Z +firstPublishedAt: 2024-12-03T19:24:22.388Z +contentType: trackArticle +productTeam: Education +slugEN: documentation-overview +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: documentation-overview +--- + +VTEX documentation is designed to provide clear and concise information for anyone interested in using or integrating with our products. Our goal is to empower clients and partners by offering resources that support learning about the platform and business development. + +In this guide, you’ll learn about how VTEX creates documentation and how you can contribute. + +## Learning resources + +At VTEX, we offer resources where you can find guides, tutorials, learning paths, product updates, and ask questions or offer help with VTEX products: + +| **Portal name** | **Description** | +| :---- | :---- | +| [Help Center](https://help.vtex.com/) | Provides beginner tutorials, reference guides, and articles. | +| [Developer Portal](https://developers.vtex.com/) | Provides information about integrations, APIs, and development resources for your store. | +| [Community](https://community.vtex.com/) | Enables connection with other users, asking questions, and sharing knowledge within the VTEX ecosystem. | +| [Learning VTEX](https://learn.vtex.com/) | Provides a learning environment on how to develop a store using [Store Framework](https://developers.vtex.com/docs/guides/store-framework) or a [VTEX App](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-a-vtex-app). | + +## Product updates + +Access the [Announcements](https://help.vtex.com/pt/en/announcements) and the [Release Notes](https://developers.vtex.com/updates/release-notes) sections to stay informed about new features, products, and documentation updates. + +## Product Documentation track content + +In this track, you’ll find the following guides. + + + + + + + + + + diff --git a/docs/en/documentation/documentation-test.md b/docs/en/documentation/documentation-test.md new file mode 100644 index 000000000..7089aeb03 --- /dev/null +++ b/docs/en/documentation/documentation-test.md @@ -0,0 +1,17 @@ +--- +title: 'Documentation test file' +id: documentation-test-file +status: PUBLISHED +createdAt: 2024-11-05T19:24:22.388Z +updatedAt: 2024-11-05T19:24:22.388Z +publishedAt: 2024-11-05T19:24:22.388Z +firstPublishedAt: 2024-11-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: documentation-test-file +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: documentation-test-file +--- + +This is a test file to check the connection between the documentation repository and the webpage repository. \ No newline at end of file diff --git a/docs/en/documentation/onboarding-template.md b/docs/en/documentation/onboarding-template.md new file mode 100644 index 000000000..3890282db --- /dev/null +++ b/docs/en/documentation/onboarding-template.md @@ -0,0 +1,67 @@ +--- +title: 'Onboarding template' +id: edu0004 +status: PUBLISHED +createdAt: 2024-12-03T19:24:22.388Z +updatedAt: 2024-12-03T19:24:22.388Z +publishedAt: 2024-12-03T19:24:22.388Z +firstPublishedAt: 2024-12-03T19:24:22.388Z +contentType: trackArticle +productTeam: Education +slugEN: onboarding-template +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: onboarding-template +--- + +Onboarding articles introduce new users to a specific technology, tool, or system to facilitate the learning curve and enable them to become proficient and productive quickly. + +In this guide, see the available template, general guidelines, and examples of Onboarding articles. + +
+Onboarding template + +```md +# Title +[Describe in this section what the technology is.] + +Ex.: To work with {technology name}, you should be familiar with the following technologies: +[Add here the technologies that the person should know before starting to work with it.] +[Technology 1](link) +[Technology 2](link) +[Technology 3](link) +… +## {technology name} architecture +[Add here a diagram illustrating the technology architecture and provide an explanation.] + +## Quickstart +[Describe the step-by-step process for developing a project using the technology, from installing the requirements to running the project locally. The steps below can vary depending on the technology.] + +### 1. Initial settings +[Describe the requirements and initial configuration needed before developing the project.] + +### 2. Setting up the project +[Provide instructions for setting up the development environment to kickstart your project and run it locally.] + +### 3. Customizing the storefront +[After running locally, describe the customization options available.] + +## Next steps +[Suggest additional initial configurations or steps for those who have completed the quickstart section, and include the card component along with the links to the suggestions.] + +``` +
+ +## General guidelines + +| Topic | Description | +| :---- | :---- | +| **Focus on Fundamentals** | Emphasize the core elements a user needs to understand to get started, such as critical dependencies, initial configurations, and key setup steps. Avoid overwhelming users with advanced configurations unless necessary for initial usage. | +| **Assets** | Whenever possible, include visuals such as diagrams, screenshots, or flowcharts. These can clarify complex processes and provide users with a quick reference. In the architecture section, a well-labeled diagram helps illustrate system components and interactions. | +| **Step-by-Step Instructions** | For sections like **Quickstart**, ensure each step is actionable and, if needed, link to additional resources for deeper understanding. | +| **Links to Prerequisites and Further Learning** | Use links to direct users to related technologies, documentation, and guides. For example, in the **Next steps** section, suggest related configurations or customizations and link to resources that expand on or complement the basic onboarding content. | + +## Examples of Onboarding articles + +* [FastStore - Overview](https://developers.vtex.com/docs/guides/faststore) +* [Store Framework - Overview](https://developers.vtex.com/docs/guides/store-framework) diff --git a/docs/en/documentation/troubleshooting-template.md b/docs/en/documentation/troubleshooting-template.md new file mode 100644 index 000000000..baad2a19e --- /dev/null +++ b/docs/en/documentation/troubleshooting-template.md @@ -0,0 +1,144 @@ +--- +title: 'Troubleshooting template' +id: edu0005 +status: PUBLISHED +createdAt: 2024-12-04T19:24:22.388Z +updatedAt: 2024-12-04T19:24:22.388Z +publishedAt: 2024-12-04T19:24:22.388Z +firstPublishedAt: 2024-12-04T19:24:22.388Z +contentType: trackArticle +productTeam: Education +slugEN: troubleshooting-template +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: troubleshooting-template +--- + +Troubleshooting articles help users find practical solutions to problems they may encounter when completing tasks on the platform. + +In this guide, see the available templates, general guidelines, and examples of troubleshooting articles. + +> ℹ️ Make sure to review the guidelines from the [Best practices for writing documentation](LINK). + +## Templates + +
+Template 1 - Error and problem groups + +```md +# Title +Product tags: [Add products related to troubleshooting. Example: Orders and Payments] + +Keywords: [Words that help identify the article content in a search. Example: Unidentified order, SKU, etc.] + +[Add a brief introduction describing the problem faced by the user. Whenever possible, limit this to 2 paragraphs.] + +## Solution +To identify the meaning and determine the specific correction for each error message, see the table below: + + +Error type or message +Meaning +Required action +`{Add the error message}` or + +Add the error type +[Describe the meaning of the message or the cause of the error type. Example: Order not found on VTEX (item removed from the catalog or incorrect information).] +[Guide the user with clear instructions. Example: provide a summary of the steps, mention another article, or recommend contacting support for further assistance.] +``` +
+ +
+Template 2 - General articles + +```md +# Title +Product tags: [Add products related to troubleshooting. Example: Orders and Payments] + +Keywords: [Words that help identify the article’s content in a search. Example: Unidentified order, SKU, etc.] + +[Add a brief introduction describing the problem faced by the user. Limit this to 2 paragraphs.] + +## Solution +[Describe possible solutions to solve the reported error. When there are multiple steps to fix the error, these should be divided into individual steps, see the next template, Template 3 - General articles: More than one step in the solution.] + +To solve this problem, there are several solutions you can consider: + +- [Solution name 1](#solution-name-1): [Describe the scenario for this problem. Example: "The Site Editor does not open."] + +- [Solution name 2](#solution-name-2): … + +### Solution name 1 +[Example title: "Checking roles"] + +[Describe what needs to be done to solve the problem and the expected outcome.] + + +### Solution name 2 +. +. +. +``` +
+ +
+Template 3 - General articles: More than one step in the solution + +```md +# Alternative title + +### Solution Name 1 +[Example Title: Configure your VTEX account] + +[Describe in investigative steps. Within each step, describe the necessary steps to solve the problem and the expected outcome.] + +### Step 1 - Step Name 1 +. +. +. + +#### Step 2 - Step Name 2 +. +. +. + +### Solution Name 2 +. +. +. +#### Step 1 - Step Name 1 +. +. +. + +#### Step 2 - Step Name 2 +. +. +. +``` +
+ +## General guidelines for troubleshooting articles + +| **Topic** | **Description** | +| :---- | :---- | +| **Title** | Clearly describe the issue in a concise and direct manner, using first-person language. | +| **Introduction** | Provide a brief overview of the problem scenario, including affected modules, error messages, and screenshots. | +| **Solution(s)** | Outline the steps to resolve the issue, including: **Solution name:** Provide a clear and concise label for each solution. **Steps:** Break down the solution into numbered steps, using clear and concise language. | +| **Assets** | Include screenshots or other visual aids to enhance understanding (if applicable). | +| **User perspective** | Write from the user's point of view, focusing on the problem they are experiencing. | +| **Product tags and keywords** | Include relevant product tags and keywords to improve search visibility. | +| **Responsibility** | Indicate who is responsible for resolving the issue and taking necessary actions: VTEX, the user, or both. | +| **Root cause analysis** | Identify the underlying cause of the problem to provide effective solutions. | + +## Examples of troubleshooting articles + +* [Help Center](https://help.vtex.com/category/troubleshooting--39pDkp8qxSll6mGj0tWViz) + * [My ad is not displayed on Mercado Livre](https://help.vtex.com/tutorial/my-ad-is-not-displayed-on-mercado-livre--2UpudfowEvG97e2lstj4qc) + * [My store’s Site Editor is not working](https://help.vtex.com/tutorial/my-stores-site-editor-is-not-working--3A6Ois91zEZ8zpKJp1wsP2) + * [Promotion not applied to the marketplace](https://help.vtex.com/tutorial/promotion-not-applied-to-the-marketplace--2pxlVpzgThuw2wTEISRwA2) + +* [Developer Portal](https://developers.vtex.com/docs/troubleshooting) + * [I can't update the EAN of my SKUs via API](https://developers.vtex.com/docs/troubleshooting/i-cant-update-the-ean-of-my-skus-via-api) + * [Modal Layout closes when I click a SKU](https://developers.vtex.com/docs/troubleshooting/modal-layout-closes-when-i-click-a-sku) + * [My store is slow or unavailable](https://developers.vtex.com/docs/troubleshooting/my-store-is-slow-or-unavailable) diff --git a/docs/en/glossary/glossary-test.md b/docs/en/glossary/glossary-test.md new file mode 100644 index 000000000..bed66cb13 --- /dev/null +++ b/docs/en/glossary/glossary-test.md @@ -0,0 +1,17 @@ +--- +title: 'glossary test file' +id: glossary-test-file +status: PUBLISHED +createdAt: 2024-11-05T19:24:22.388Z +updatedAt: 2024-11-05T19:24:22.388Z +publishedAt: 2024-11-05T19:24:22.388Z +firstPublishedAt: 2024-11-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: glossary-test-file +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: glossary-test-file +--- + +This is a test file to check the connection between the documentation repository and the webpage repository. \ No newline at end of file diff --git a/docs/en/grammar/adjectives.md b/docs/en/grammar/adjectives.md new file mode 100644 index 000000000..d2d0152ad --- /dev/null +++ b/docs/en/grammar/adjectives.md @@ -0,0 +1,45 @@ +--- +title: 'Adjectives' +id: grammar0002 +status: PUBLISHED +createdAt: 2025-01-09T19:24:22.388Z +updatedAt: 2025-01-09T19:24:22.388Z +publishedAt: 2025-01-09T19:24:22.388Z +firstPublishedAt: 2025-01-09T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: adjectives +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: adjectives +--- + +Adjectives come before the noun. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • The main criteria for white label seller selection are: | • The main criteria for seller white label selection are: | + +To be more objective, avoid using too many adjectives. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • In the next step, click \`Payments\`.
• The store setup will be complete after completing this step. | • The next step is very easy, just click \`Payments\`.
• Please make sure to complete this step. It is a really important step in completing the store setup. | + +Past participles can be part of verb tenses or adjectives describing a noun or a completed action. When they act as a verb, they come after the noun, and when they act as an adjective, they come before. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Product added to cart successfully
• Added products are also ranked in the first positions | • Added product to cart successfully
• Products added are also ranked in the first positions | + +Nouns can act as attributive adjectives to indicate possession, measurement, or source. Attributive adjectives are used to express these qualities concisely, often in lieu of the preposition “of” or a possessive with apostrophe “‘s.” + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • The event list will not be in chronological order.
• In the Admin, you have the flexibility of customizing store typography to meet your business needs.
• Ask the store frontend admin for help. | • The list of events will not be in chronological order.
• In the Admin, you have the flexibility to customize your store's typography to meet your business needs.
• Ask your store's front-end admin for help. | + +Nouns acting as adjectives are used in singular. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Order Management
• Seller Portal | • Orders Management
• Sellers Portal | diff --git a/docs/en/grammar/capitalization.md b/docs/en/grammar/capitalization.md new file mode 100644 index 000000000..803493363 --- /dev/null +++ b/docs/en/grammar/capitalization.md @@ -0,0 +1,131 @@ +--- +title: 'Capitalization' +id: grammar0001 +status: PUBLISHED +createdAt: 2025-01-09T19:24:22.388Z +updatedAt: 2025-01-09T19:24:22.388Z +publishedAt: 2025-01-09T19:24:22.388Z +firstPublishedAt: 2025-01-09T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: capitalization +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: capitalization +--- + +## General + +Use sentence case capitalization for documentation, including headings and all UI elements. This means capitalizing only the first letter of the first word in a sentence or phrase, except for proper nouns and acronyms. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Create account
• Try new experience
• Getting started with Ad Network
• Starting the integration with Catalog
• Merchant ID
• Copy URL to clipboard
• Activate seller
• Deactivate seller
| • Create account
• Try New Experience
• Getting started with Ad Network
• Starting the integration with Catalog
• Merchant id
• Copy url to clipboard
• Activate Seller
• Deactivate Seller | + +## Proper nouns + +Capitalize all proper or trademarked nouns, including names of **products**, **features, modules, pages,** **people, places, nationalities, names of languages, months, days of the week,** and **holidays**. If the noun has more than one word, use title case. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Black Friday will be on November 24
• Intelligent Search determines the relevance of each product by combining weights.
• Contact the VTEX Support team.
• Contact the Support team \- Short alternative option for \*VTEX Support team\*.
• Requesting a trade policy for the Brazilian market.
• Personal Shopper is available in the following languages: English, Spanish, Portuguese, French, and German.
• Export to Excel
• Install Intelligent Search
• VTEX App Store | • Black friday will be on november 24
• Intelligent search determines the relevance of each product by combining weights.
• Contact the support team.
• Requesting a trade policy for the brazilian market.
• Personal Shopper is available in the following languages: english, spanish, portuguese, french, and german.
• Export to excel
• Install intelligent search
• VTEX app store | + +Respect the capitalization of company names as used in their copy material (not their logo), whether it’s all caps, a capital letter in between, or all lowercase. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • VTEX
• VTEX
• SAP
• ServiceNow | • Vtex
• vtex
• Sap
• Servicenow | + +If an official name begins with a lowercase letter, use it in lowercase even at the start of a sentence. If possible, rewrite the sentence to avoid a lowercase word at the beginning. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • To configure the easypay affiliation, follow the steps below:
• Checkout customization for easypay
• VTEX is the highest-ranked “Leader” | • To configure the Easypay affiliation, follow the steps below:
• easypay checkout customization
• Vtex is the highest-ranked “Leader” | + +### Letters following slashes + +When a slash joins words, capitalize the word after the slash if the word before the slash is capitalized. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Items/Units
• Note/Sales associate code
• Package/Order number | • Items/units
• Note/sales associate code
• Package/order number | + +### File formats + +Capitalize file formats. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Export to CSV | • Export to csv | + +### Endpoints and APIs + +Capitalize the first word of labels and terms in APIs unless they're always lowercase. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Create or update promotion endpoint
• The Conversions API | • Create Or Update Promotion endpoint
• The conversions API | + +## Acronyms + +Most acronyms are fully capitalized, but not all. Follow the standard form used in the industry. Capitalize all words in the spelled-out form of an acronym. The names of many protocols and specifications are considered proper nouns and are capitalized when spelled out. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Renew the API token before the duration ends.
• This option involves using a third-party platform, known as Platform as a Service (PaaS).
• How does VTEX ensure compliance with the General Data Protection Regulation (GDPR)?
• Multiple redirects are possible in a single URL.
• A user ID screen is displayed so that the customer can continue trying to purchase. | • Renew the api token before the duration ends.
• This option involves using a third-party platform, known as platform as a service (PAAS).
• How does VTEX ensure compliance with the general data protection regulation (GDPR)?
• Multiple redirects are possible in a single url.
• A user id screen is displayed so that the customer can continue trying to purchase. | + +## Colons + +Capitalize the first letter after a colon. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Autocomplete: Provides search and product suggestions based on the shopper's context. | • Autocomplete: provides search and product suggestions based on the shopper's context. | + +## User interfaces + +Actions and nouns listed in action and content labels (including dropdown menus and filters) should be capitalized. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Edit
• Export file
• Import file | • edit
• export file
• import file | + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| Filter by status:
• Confirmed
• Expired
• Handled | Filter by status:
• confirmed
• expired
• handled | + +## Documentation + +## User Interface elements + +Follow the capitalization used on the UI including labels, buttons, and VTEX Admin module names. This also applies to UI from other platforms. + +![Google Tag Manager example](https://github.com/vtexdocs/language-hub-content/blob/main/images/en/capitalization.png?raw=true) + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • In the **Google Tag Manager** field, enter the store identification code in **GTM-XXXX** format, as shown in the image below. | • In the **Google tag manager** field, enter the store identification code in **gtm-XXXX** format, as shown in the image below. | + +## Technical references and developer fields + +Use camel case for placeholders and developer fields. This means capitalizing the first letter of each word, except for the first letter of the entire compound word. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • The file name should follow the pattern *{storeName}-favicon.ico*. | • The file name should follow the pattern *{storename}-favicon.ico*. | + +## Lists + +Always capitalize the first letter in a bullet or numbered list. + +### Bullet list + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| Search Console provides easy and free access to the following information:
1. Top search terms
2. Top URLs viewed | Search Console provides easy and free access to the following information:
• top search terms
• top URLs viewed | + +### Numbered list + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| On the \*\*Projects\*\* page, click \`Create new\`.
In the \*\*New project\*\* page, complete the fields.
After setting each field of the page, click \`Create\`. | on the \*\*Projects\*\* page, click \`Create new\`.
in the \*\*New project\*\* page, complete the fields.
after setting each field of the page, click \`Create\`. | diff --git a/docs/en/grammar/contractions.md b/docs/en/grammar/contractions.md new file mode 100644 index 000000000..3c9005b6b --- /dev/null +++ b/docs/en/grammar/contractions.md @@ -0,0 +1,33 @@ +--- +title: 'Contractions' +id: grammar0004 +status: PUBLISHED +createdAt: 2025-01-09T19:24:22.388Z +updatedAt: 2025-01-09T19:24:22.388Z +publishedAt: 2025-01-09T19:24:22.388Z +firstPublishedAt: 2025-01-09T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: contractions +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: contractions +--- + +Use common contractions, such as negation, and *it’s,* *you’re*, *that's*, to reflect a friendly tone. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Order Management
• Seller Portal | • Orders Management
• Sellers Portal | + +Avoid awkward contractions, such as *there’d*, *it’ll*, *they’d,* noun plus verb, and double. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • You should have installed the app before proceeding. | • You should've installed the app before proceeding. | + +List of some awkward and common contractions: + +| Common ✅ | Awkward ❌ | +| --------- | ------------ | +| • You’re (You are)
• They’re (They are)
• They’ve (They have)
• It’s (It is / It has)
• You'll (You will)
• Don’t (Do not)
• Won’t (Will not)
• Can’t (Cannot)
• Shouldn’t (Should not) | • The system’s (The system is)
• The platform’s (The platform is / has)
• The data’s (The data is / has)
• There’re (There are) – Awkward because it’s harder to pronounce clearly.
• That’ll (That will) – Sounds overly casual.
• Who’d’ve (Who would have) – Rarely seen outside very casual speech.
• Shouldn’t’ve (Should not have) – Too convoluted for writing. | diff --git a/docs/en/grammar/grammar-test.md b/docs/en/grammar/grammar-test.md new file mode 100644 index 000000000..104602819 --- /dev/null +++ b/docs/en/grammar/grammar-test.md @@ -0,0 +1,17 @@ +--- +title: 'grammar test file' +id: grammar-test-file +status: PUBLISHED +createdAt: 2024-11-05T19:24:22.388Z +updatedAt: 2024-11-05T19:24:22.388Z +publishedAt: 2024-11-05T19:24:22.388Z +firstPublishedAt: 2024-11-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: grammar-test-file +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: grammar-test-file +--- + +This is a test file to check the connection between the documentation repository and the webpage repository. \ No newline at end of file diff --git a/docs/en/grammar/pronouns.md b/docs/en/grammar/pronouns.md new file mode 100644 index 000000000..a60d752cb --- /dev/null +++ b/docs/en/grammar/pronouns.md @@ -0,0 +1,33 @@ +--- +title: 'Pronouns' +id: grammar0003 +status: PUBLISHED +createdAt: 2025-01-09T19:24:22.388Z +updatedAt: 2025-01-09T19:24:22.388Z +publishedAt: 2025-01-09T19:24:22.388Z +firstPublishedAt: 2025-01-09T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: pronouns +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: pronouns +--- + +Use "their" when talking about a third-person singular. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • When you click a seller, you are redirected to their details page. | • When you click a seller, you are redirected to his details page. | + +Always address the reader as you. Use the words *user, merchant, or seller* only to refer to the user of the feature that your reader is configuring. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • In this section, you can select the offers that will be included in the promotion. To include offers in the promotional campaign, follow the steps below:
1. In the **Candidates** section, check the checkbox of the offers that you want to include in the promotional campaign. | • In this section, the seller will select the offers that will be included in the promotion. To include offers in the promotional campaign, follow the steps below:
2. In the **Candidates** section, check the checkbox of the offers that the seller wants to include in the promotional campaign. | + +Use first-person plural pronouns (*we, our, us*) to refer to VTEX as author of the document when necessary. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • We recommend adjusting this setting to avoid stockout.
• We recommend exporting 10,000 records at a time. | • VTEX recommends adjusting this setting to avoid stockout.
• It's recommended to export 10,000 records at a time. | diff --git a/docs/en/guides/guides-test.md b/docs/en/guides/guides-test.md new file mode 100644 index 000000000..8b5f29a0c --- /dev/null +++ b/docs/en/guides/guides-test.md @@ -0,0 +1,17 @@ +--- +title: 'guides test file' +id: guides-test-file +status: PUBLISHED +createdAt: 2024-11-05T19:24:22.388Z +updatedAt: 2024-11-05T19:24:22.388Z +publishedAt: 2024-11-05T19:24:22.388Z +firstPublishedAt: 2024-11-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: guides-test-file +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: guides-test-file +--- + +This is a test file to check the connection between the documentation repository and the webpage repository. \ No newline at end of file diff --git a/docs/en/guides/product-and-feature-naming.md b/docs/en/guides/product-and-feature-naming.md new file mode 100644 index 000000000..4c83b2cb3 --- /dev/null +++ b/docs/en/guides/product-and-feature-naming.md @@ -0,0 +1,212 @@ +--- +title: 'Product and feature naming' +id: guides0001 +status: PUBLISHED +createdAt: 2025-01-09T19:24:22.388Z +updatedAt: 2025-01-09T19:24:22.388Z +publishedAt: 2025-01-09T19:24:22.388Z +firstPublishedAt: 2025-01-09T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: product-and-feature-naming +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: product-and-feature-naming +--- + +## Objective + +Establish a clear, consistent, and meaningful naming strategy for VTEX products, features, and projects to enhance brand identity, customer understanding, and market positioning. This strategy aims to ensure that names are descriptive, practical, and aligned with industry standards, making them easy to spell, pronounce, and remember. + +By implementing these guidelines, VTEX will create a cohesive naming convention that facilitates communication, supports marketing efforts, and strengthens the overall VTEX brand in the global marketplace. + +Why have a naming process? + +**Consistency:** Ensures all names align with the [brand's identity and values](https://brand.vtex.com/), creating a unified image. + +**Clarity:** Helps customers easily understand what each product, feature, or module does, reducing confusion. + +**Professionalism:** Demonstrates a well-organized and thoughtful approach, enhancing the company's reputation. + +**Market Positioning:** Differentiates VTEX products from competitors and clearly communicates their unique value. + +**Global Relevance:** Ensures names are appropriate and understandable across different languages and cultures. + +**Efficiency:** Streamlines the naming process, saving time and resources by providing clear guidelines and reducing the need for ad-hoc decisions. + +**Marketing and SEO:** Improves searchability and marketing effectiveness by using names that are easy to find and understand online. + +When does this process apply? + +* Launching new products; +* Developing features and modules; +* Updating existing names; +* Adapting names for different regions and languages. + +When to run the naming process? + +**The sooner, the better.** Ideally, run this process at least 2 months before rolling out to closed beta. + +### General guidelines + +Names must be: + +**Meaningful:** Conveys relevant meaning and fits within the industry; use terms that are commonly used and easily recognizable by merchants. + +**Unique:** Differentiates from competitors and is not too generic. + +**Memorable:** Easy to remember and recognize. + +**Easy to Spell:** Should be spelled as it is pronounced. + +**Easy to Pronounce:** Should be pronounced as it is spelled. + +**Brief:** Limited to one or two words, max of three, or a compound word. + +**Weighty:** Conveys strength and importance. + +**Global Relevance:** Ensure names are easy to understand in different languages and cultures. + +**SEO Friendly:** Names should be searchable and rankable. + +**Word Choice:** Opt for words with positive connotations and impact to ensure memorable and engaging names. + +Specific guidelines + +**Versioning and Updates:** Use [semantic versioning](https://www.notion.so/vtexhandbook/POC-MVP-Alpha-Beta-what-and-when-do-we-communicate-things-6eee838febdd48feb0d60d00b9173ffa) for updates to existing features rather than renaming them. Add “(Beta)” for test pages and “(Legacy)” for outdated systems. + +**Translations:** We use different translation strategies for products, modules, and features to ensure brand consistency and recognition across all markets. + +**Products:** Keep in English. + +* Examples: Sales App, Live Shopping, FastStore. + **VTEX Admin Modules:** Translated. +* Examples: Overview / Visão geral, Shipping / Envio, Orders / Pedidos + **Permission Roles:** Not translated. +* Examples: Owner (Admin Super), VTEX IO Admin. + **Features:** Translated. +* Example: Operational capacity / Capacidade operacional. + **Apps:** Some are translated, some are not. +* Examples: Wishlist / Lista de desejos, Customer Credit. + +**Capitalization:** Capitalization rules differ by language. Use title case for titles in English, and sentence case in Portuguese and Spanish. For more details, see our [style guides](https://language.vtex.com/content/style_guides.html) or contact the Localization team. + +**Character Limit:** + +* Modules \- 18 characters +* Sections \- 16 characters +* Subsections \- 21 characters + + +What to avoid + +* Don’t use verbs. For example, use “Available Sellers” instead of “Find Sellers.” +* Don’t use punctuation. +* Don’t use personal pronouns. +* Avoid redundancy or repeat unnecessary terms. Example: avoid repeating the section title, such as when using the words *Management* or *List*. + +* Avoid using abbreviations unless they are widely recognized and understood, such as “B2B” or “SKU.” + +Naming examples + +**VTEX Product Names** (examples)**:** + +* VTEX Commerce Platform +* VTEX IO Development Platform +* VTEX Live Shopping +* VTEX Tracking +* VTEX Shipping Network + +**VTEX Module Names** (examples)**:** + +* VTEX Marketplace +* VTEX OMS (order management system) +* VTEX Intelligent Search +* VTEX CMS (content management system) +* VTEX IO Store Framework +* VTEX IO FastStore +* VTEX IO WebOps +* VTEX IO App Platform + +**VTEX Feature Names** (examples)**:** + +* VTEX Promotions +* VTEX Catalog +* VTEX Master Data +* VTEX Sales Dashboard + + +### Streamlined process for simpler features + +1. Fill a workflow + * Fill out the product-naming workflow in the \#terminology Slack group to ensure all relevant teams are informed, aligned, and participating in the naming process. + 1. Key drivers/contributors: PMs, Designers. +2. Necessity check: + * Determine if a new name is truly necessary. Evaluate if an existing name can be adapted or if the new feature/module/product can fit under an existing naming convention. + 1. Key drivers/contributors: PMs or Designers (when creating the request), Localization (when analyzing the task to proceed to step 3). +3. Generate name ideas: + * Analyze how competitors name similar products and features; + * Create a short list of possible names; + * Check for alignment with VTEX’s strategy and brand guidelines + 1. Key drivers/contributors: PMs or Designers (when creating the request), Localization (when doing the brainstorm for naming suggestions). +4. Team discussion: + * Validate names with the requester, and the Localization and Product Marketing teams to ensure they are suitable across different languages and markets; + * Collect internal feedback and refine the list based on input. This can be done publicly in the thread opened on the terminology channel so everyone interested can contribute. + 1. Key drivers/contributors: Localization, PMs, PMMs, Designers, and anyone else who contributed to the discussion in the thread. +5. Implementation: + * Review the feedback and decide the name that best fits the criteria; + * Once there’s a final decision, make it clear on the request thread; + * Socialize it with relevant stakeholders; + * Ensure all marketing materials, product documentation, and internal communications use the new name consistently. + 1. Key drivers/contributors: Localization, Education, PMs and PMMs. + + Comprehensive process for big product launches + +1. Fill a workflow + * Fill out the product-naming workflow in the \#terminology Slack group to ensure all relevant teams are informed, aligned, and participating in the naming process. + 1. Key drivers/contributors: PMs, Designers +2. Necessity check: + * Determine if a new name is truly necessary. Evaluate if an existing name can be adapted or if the new feature/module/product can fit under an existing naming convention. + 1. Key drivers/contributors: PMs, working collaboratively to determine the necessity of a new name and evaluate existing naming conventions. +3. Research and validation: + * Begin [documenting](https://docs.google.com/document/d/1cBrYkQuUQAg-FFxCL6-HQIS90rw6PUhEZbXolp4CWB8/edit?usp=sharing) the step-by-step process for defining the name; + * Analyze how competitors name similar products and features; + * Check if customer interviews have been conducted for insights on how they refer to the feature or product. If not, consider conducting one. + 1. Key drivers/contributors: PMMs, PMs and Product Designers + 1. PMM: Begin documenting, lead competitor analysis and provide market insights relevant to naming; + 2. PM and PD: Ensure customer interviews are conducted and identify gaps for additional insights +4. Generate name ideas: + * Create an exhaustive list of potential names; + * Evaluate each name against the guidelines (meaningful, unique, memorable, etc.); + * Conduct a comprehensive trademark search to ensure the proposed name isn’t already in use or registered by another entity; + * Ensure the names align with VTEX’s overall company strategy, product portfolio, and brand architecture. + 1. Key drivers/contributors: PMs, PMMs, Education and Localization + 1. PM & PMM: Generate an exhaustive list of potential names. + 2. PMM: Conduct a comprehensive trademark search. + 3. Education and Localization: Provide feedback on name clarity and cultural appropriateness. +5. Team discussion: + * Validate names with localization and product marketing teams to ensure they are suitable across different languages and markets; + * Collect feedback and refine the list based on input. + 1. Key drivers/contributors: Localization, PMMs and PM + 1. Localization: Validate names for suitability across different languages and markets. + 2. PMM & PM: Refine the name list based on feedback. +6. Testing: + * Consider testing a shortlist of names with sponsor clients, friendly customers, related internal teams, and business partners; + * Document responses, likes, and dislikes to gather insights. + 1. Key drivers/contributors: PMMs and Product Designers + 1. PMMs & PD: Test a shortlist of names with sponsor clients, friendly customers, related internal teams, and business partners and gather insights. +7. Final decision: + * Review the feedback and finalize the name that best fits the criteria; + * Validate the chosen name with [Alexandre Gusmão](mailto:alexandre.gusmao@vtex.com) and [Natalia Costa](mailto:natalia.costa@vtex.com). + 1. Key drivers/contributors: PMs and PMMs collaborate in finalizing the name that best fits the criteria, and validate it with Leadership. +8. Implementation: + * Complete the step-by-step process [document](https://docs.google.com/document/d/1cBrYkQuUQAg-FFxCL6-HQIS90rw6PUhEZbXolp4CWB8/edit?usp=sharing) and communicate the chosen name; + * Socialize it with stakeholders in product, marketing, sales, solution engineering, and customer success; + * Ensure all marketing materials, product documentation, and internal communications use the new name consistently. + 1. Key drivers/contributors: PMMs, PMs, Education, and Localization + 1. PMMs: Complete the step-by-step process document, communicate the chosen name; + 2. PMMs, PMs, Education, and Localization: Collaborate on socializing the name as well as ensure the consistency usage of it. + +### Seek assistance if needed + +If doubts persist after following the process, consult with the Product Marketing team for additional guidance and final decision-making support. diff --git a/docs/en/style-guides/test.md b/docs/en/style-guides/test.md new file mode 100644 index 000000000..e5bafbdfb --- /dev/null +++ b/docs/en/style-guides/test.md @@ -0,0 +1,17 @@ +--- +title: 'Test file' +id: 1ZWhHn9uWxLlk7GoVTAzYe2 +status: PUBLISHED +createdAt: 2020-01-07T19:24:22.388Z +updatedAt: 2021-04-08T14:56:26.279Z +publishedAt: 2021-04-08T14:56:26.279Z +firstPublishedAt: 2020-01-13T14:32:45.916Z +contentType: trackArticle +productTeam: Identity +slugEN: test +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: test-file +--- + +This is a test file to check the connection between the documentation repository and the webpage repository. \ No newline at end of file diff --git a/docs/en/user-interfaces/articles.md b/docs/en/user-interfaces/articles.md new file mode 100644 index 000000000..c4830cdfd --- /dev/null +++ b/docs/en/user-interfaces/articles.md @@ -0,0 +1,48 @@ +--- +title: 'Articles' +id: ui0001 +status: PUBLISHED +createdAt: 2024-09-13T19:24:22.388Z +updatedAt: 2024-09-16T14:56:26.279Z +publishedAt: 2024-11-28T14:56:26.279Z +firstPublishedAt: 2024-11-28T14:56:26.279Z +contentType: trackArticle +productTeam: Localization +slugEN: articles +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: articles +--- + +To convey an objective and concise message, avoid using articles. + +Keep button labels short to encourage action. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| Add product | Add a product | + +Use articles when the message is longer and requires explanation. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| Add a new pickup point address | Add new pickup point address | + +Do not use articles with proper nouns. The exceptions are when product names are treated as common nouns. + + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| Use the integration with Intelligent search Order {orderId} will be canceled on Sales App | Use the integration with the Intelligent search. Order {orderId} will be canceled on the Sales App | + +Use articles when product names are treated as common nouns. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| Test the new version of the VTEX Admin You can contact our team through the Help Center. | Test the new version of VTEX Admin You can contact our team through Help Center. | + +The indefinite article used before SKU (Stock Keeping Unit) can vary depending on its pronunciation. It can be pronounced either as individual letters (/ˌɛsˌkeɪˈjuː/), which requires “an,” or as a single syllable (/skjuː/), which takes “a.” At VTEX, we use the syllable pronunciation (/skjuː/), so the preferred form is “a SKU.” + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| A SKU | An SKU | diff --git a/docs/en/user-interfaces/ui-focused-action-labels.md b/docs/en/user-interfaces/ui-focused-action-labels.md new file mode 100644 index 000000000..567a54128 --- /dev/null +++ b/docs/en/user-interfaces/ui-focused-action-labels.md @@ -0,0 +1,70 @@ +--- +title: 'Action labels' +id: ui0004 +status: PUBLISHED +createdAt: 2024-12-05T19:24:22.388Z +updatedAt: 2024-12-05T19:24:22.388Z +publishedAt: 2024-12-05T19:24:22.388Z +firstPublishedAt: 2024-12-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: action-labels +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: action-labels +--- + +### Action labels use up to three words to indicate an action that the user wants or needs to perform. This pattern is often seen in components such as Buttons or Menus. + +### General + +### Keep it as short as possible while still being descriptive enough. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Add product | • Add new product to catalog | + +### Use a verb in the infinitive followed by an object. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Create product Visit store | • New product Store | + +### Reuse labels for the same action. Common labels can be found in the glossary. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Add product
• View details
• Edit
• Rename | • Insert product
• See details
• Modify
• Change name | + +### Use sentence case but capitalize proper nouns. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Try new experience | • Try New Experience | + +### Don’t use punctuation or personal pronouns and avoid articles. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Add product
• Preview content | • Add a product
• Preview my content | + +Specific + +### Use precise labels that reflect the exact action. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Publish
• Rename
• Learn more | • Confirm
• Edit
• Click here | + +### When the context implies a single clear object, remove the object name from the label. + +| Do ✅ | Don't ❌ | +| :------------------------------------------ | :------------------------------------------- | +| • Content label: Product
Action label: Edit
• Content label: Order
Action label: Invoice | • Content label: Product
Action label: Edit product
• Content label: Order
Action label: Invoice order | + + +### When a link is within a paragraph, it's not necessary to modify capitalization or start with a verb. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • This metric is only available for stores that capture navigation data. | • This metric is only available for stores that Capture navigation data. | diff --git a/docs/en/user-interfaces/ui-focused-content-labels.md b/docs/en/user-interfaces/ui-focused-content-labels.md new file mode 100644 index 000000000..87388d372 --- /dev/null +++ b/docs/en/user-interfaces/ui-focused-content-labels.md @@ -0,0 +1,65 @@ +--- +title: 'Content labels' +id: ui0008 +status: PUBLISHED +createdAt: 2024-12-06T19:24:22.388Z +updatedAt: 2024-12-06T19:24:22.388Z +publishedAt: 2024-12-06T19:24:22.388Z +firstPublishedAt: 2024-12-06T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: content-labels +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: content-labels +--- + +### Content labels consist of up to three words to identify data properties and values. This pattern is typically found in components like Inputs or Tables. + +### Keep it as short as possible while still being descriptive enough. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Payment pending | • Waiting for payment | + +### Reuse labels for the same property. Existing labels can be found in the glossary. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Name
• ID
• Tags | • Title
• Identification
• Labels | + +### Don't include redundant words already mentioned in the context. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Page title: Promotions
Label: Name
• Page title: Products
Label label: Status | • Page title: Promotion
Field label: Promotion name
• Page title: Products
Label label: Product status | + +### Use sentence case, but capitalize proper nouns. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Publish date
• Email address
• VTEX Seller | • Publish Date
• EMAIL ADDRESS
• Vtex seller | + +### Don’t use verbs. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Name
• Status | • Enter the name
• Select status | + +### Don't use personal pronouns. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • VTEX account
• Personal email | • My VTEX account
• My email | + +### Don't include negative words. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • More than 6 months | • Not in the last 6 months | + +### Don't use punctuation, separators, periods, commas, interrogations. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Active | • Status: active. | diff --git a/docs/en/user-interfaces/ui-focused-descriptions.md b/docs/en/user-interfaces/ui-focused-descriptions.md new file mode 100644 index 000000000..7a474119b --- /dev/null +++ b/docs/en/user-interfaces/ui-focused-descriptions.md @@ -0,0 +1,75 @@ +--- +title: 'Descriptions' +id: ui0005 +status: PUBLISHED +createdAt: 2024-12-05T19:24:22.388Z +updatedAt: 2024-12-05T19:24:22.388Z +publishedAt: 2024-12-05T19:24:22.388Z +firstPublishedAt: 2024-12-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: descriptions +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: descriptions +--- + +### Descriptions use a single sentence to clarify or explain complex information or tasks to the user. This pattern is frequently found in form fields and help-related components. + +### General + +#### Include a description only when additional information is actually necessary. + +| Do ✅ | Don't ❌ | +| :------------------------------------------ | :------------------------------------------- | +| • Label: Category
• Label: Phone | • Label: Category
Description: Complete the category
• Label: Phone
Description: Example: +1-576-158-4127 | + +#### Keep it as short as possible while still being descriptive enough. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Volume of sessions in the intermediate stages of the purchase flow | • This chart allows you to track the volume of sessions in the intermediate stages of the purchase flow and view opportunities for optimizing the conversion rate | + +#### Use sentence case, but capitalize proper nouns. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Schedule for updates
• Seller identifier in the marketplace
• Performance analysis of all VTEX Shipping Network carriers | • Schedule for Updates
• Seller identifier in the Marketplace
• Performance analysis of all VTEX shipping network carriers | + +#### Avoid punctuation such as commas, and don't use periods or question marks. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Day in which the changes made will be published considering the time zone where the store is located | • Considering the time zone where the store is located, the day in which the changes made will be published. | + +#### Don't include redundant words. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Label: Frequency
Description: Schedule for updates | • Label: Frequency
Description: Frequency for updates | + +#### Don't use a marketing tone of voice or explain benefits. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Volume of sessions in the intermediate stages of the purchase flow | • Track the volume of sessions in the intermediate stages of the purchase flow to optimize your conversion rate | + +### Specific + +#### When explaining a label, write as if completing the sentence “This is the…”. Start with a noun followed by additional information, such as conditions and definitions. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Label: Seller ID
Description: Seller identifier in the marketplace
• Label: Frequency
Description: Schedule for updates
• Label: Privacy policy
Description: Declaration of the parties that manage customer data
• Label: Publish date
Description: Day in which the changes made will appear in the store | • Label: Seller ID
Description: This is the seller identifier in the marketplace
• Label: Frequency
Description: Frequency is the schedule for updates
• Label: Privacy policy
Description: Fill a declaration of which parties manage customer data
• Label: Publish date
Description: When should the changes appear in the store? | + +#### When explaining how information given in a form field will be used, write as if completing the sentence “When you enter a value in this field, it…” and start with a verb in the simple present tense. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Label: Seller ID
Description: Appears to customers in the store
• Label: Frequency
Description: Defines when updates will be published
• Label: Privacy policy
Description: Appears to customers in the store
• Label: Publish date
Description: Considers the time zone where the store is located
| • Label: Seller ID
Description: When you fill a value in this field, it appears to customers in the store
• Label: Frequency
Description: Frequency defines when updates will be published
• Label: Privacy policy
Description: This appears to customers in the store
• Label: Publish date
Description: Consider the time zone where the store is located | + +#### When explaining both the label of a form field and how its value will be used, combine the two sentences described in the previous topics and adapt them if necessary. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Label: Seller ID
Description: Seller identifier in the marketplace that appears to customers in the store
• Label: Frequency
Description: Schedule for updates that defines when they will be published
• Label: Privacy policy
Description: Declaration of which parties manage customer data that will appear to customers in the store
• Label: Publish date
Description: Day in which the changes made will be published considering the time zone where the store is located
| • Label: Seller ID
Description: Fill the seller identifier in the marketplace that will appear to customers in the store
• Label: Frequency
Description: Frequency is the schedule for updates that defines when they will be published
• Label: Privacy policy
Description: This is a declaration of which parties manage customer data that will appear to customers in the store
• Label: Publish date
Description: When should the changes made be published, considering the time zone where the store is located? | diff --git a/docs/en/user-interfaces/ui-focused-messages.md b/docs/en/user-interfaces/ui-focused-messages.md new file mode 100644 index 000000000..679b02781 --- /dev/null +++ b/docs/en/user-interfaces/ui-focused-messages.md @@ -0,0 +1,87 @@ +--- +title: 'Messages' +id: ui0006 +status: PUBLISHED +createdAt: 2024-12-05T19:24:22.388Z +updatedAt: 2024-12-05T19:24:22.388Z +publishedAt: 2024-12-05T19:24:22.388Z +firstPublishedAt: 2024-12-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: messages +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: messages +--- + +### Messages consist of up to two sentences to communicate the system's current state and provide feedback on user actions. This pattern is commonly found in components like Inputs or Alerts. + +### General + +#### Keep it as short as possible while still being descriptive enough. Also, remember there’s a 240-character limit per message. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Provider could not be saved due to a technical issue
• Check this option
• Select at least one option
• Products could not be imported because the CSV file is invalid | • We faced an unexpected issue while attempting to save the provider. There might be several reasons for this, such as server downtime or network errors.
• Check this
• Select at least one
• Something went wrong | + +#### Don't use technical language. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Invoice could not be sent due to a technical issue | • Error 298dx9283 prevented the invoice from being sent | + +#### Reuse messages (or their structure) whenever possible. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Collection exported successfully
• Provider could not be saved due to a technical issue
• Enter this information
• Check this option
• Select at least one option | • The collection was successfully exported.
• A technical issue prevented the provider from being saved
• This field is required
• This option needs to be checked
• At least one option needs to be selected | + +#### Don't use personal pronouns. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Account created successfully
• Double-check the password | • Your account was successfully created
• You entered the wrong password. | + +#### Use an objective and neutral tone. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Invoice could not be sent due to a technical issue
• Products could not be imported because the CSV file is invalid
• Account created successfully
• Log in to your Admin
• Double-check the password
• Enter this information | • Oops, something went wrong, and the invoice could not be sent
• Please upload a valid CSV file
• Account successfully created!
• Hello. Log in to your Admin
• Unfortunately, the password is incorrect
• Please enter this information | + +#### Use common contractions. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Provider couldn't be saved due to a technical issue | • Provider could not be saved because of a technical issue | + +#### Use punctuation only when a larger message is extremely necessary. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • The store is being edited live. Changes will have immediate effect.
• File could not be processed because its size is larger than 10MB
• Collection deleted successfully
• Double-check the password
• Upload an image up to 5 MB | • The store is being edited live and changes will have immediate effect.
• Sorry, your file is too large. To avoid errors, try files under 10 MB.
• Collection deleted successfully!
• The password is incorrect, please try again.
• This file is too large, please upload an image with 5MB at most. | + +#### Use sentence case, but capitalize proper nouns. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Collection exported successfully
• Notifying Intelligent Search indexer | • Collection Exported Successfully
• Notifying intelligent search indexer | + +### Specific + +#### For the error texts in a form field, start with an imperative verb. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Complete this field
• Check this option
• Select at least one option | • This field is required
• This option needs to be checked
• At least one option needs to be selected | + +#### In modals that confirm actions, personal pronouns, and question marks can be used. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • This action can’t be undone. Are you sure you want to delete this product? | • Do you want to delete this product? This can't be undone. | + +#### For consistency, place the adverb “successfully” at the end of the phrase. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Order placed successfully
• Collection exported successfully. | • Your order was successfully placed
• The collection was successfully exported | diff --git a/docs/en/user-interfaces/ui-focused-placeholder-texts.md b/docs/en/user-interfaces/ui-focused-placeholder-texts.md new file mode 100644 index 000000000..f5fbfb86c --- /dev/null +++ b/docs/en/user-interfaces/ui-focused-placeholder-texts.md @@ -0,0 +1,45 @@ +--- +title: 'Placeholder texts' +id: ui0007 +status: PUBLISHED +createdAt: 2024-12-06T19:24:22.388Z +updatedAt: 2024-12-06T19:24:22.388Z +publishedAt: 2024-12-06T19:24:22.388Z +firstPublishedAt: 2024-12-06T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: placeholder-texts +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: placeholder-texts +--- + +### Placeholder texts use a single sentence to guide the user on how to interact with a form field before any value is entered. This pattern is commonly found in components like Search and Select fields. + +### General + +#### Avoid custom placeholder text. The user should intuitively know what information to enter. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Search
• Select… | • Search by name
• Select an option... | + +#### Don't include redundant words. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Page title: Products
Field placeholder: Search by category or ID
• Field label: Category
Field placeholder: Select… | • Page title: Products
Field placeholder: Search by product category or product ID
• Field label: Category
Field placeholder: Select a category… | + +#### Write at most 36 characters. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Search by name, ID, or ref ID | • Search by name, category, description, ID, or ref ID | + +### Specific + +#### When writing the placeholder text of a Select field, include an ellipsis at the end. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| • Select… | • Select | diff --git a/docs/en/user-interfaces/ui-focused-punctuation.md b/docs/en/user-interfaces/ui-focused-punctuation.md new file mode 100644 index 000000000..b4ca628b9 --- /dev/null +++ b/docs/en/user-interfaces/ui-focused-punctuation.md @@ -0,0 +1,36 @@ +--- +title: 'Punctuation' +id: ui0002 +status: PUBLISHED +createdAt: 2024-12-05T19:24:22.388Z +updatedAt: 2024-12-05T19:24:22.388Z +publishedAt: 2024-12-05T19:24:22.388Z +firstPublishedAt: 2024-12-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: punctuation +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: punctuation +--- + +### In a UI, the goal is to minimize distractions and guide users through clear actions and messages. The UI must be concise, functional, and often minimal in its use of punctuation. + +### Avoid using periods to end single sentences, particularly in labels, label description text, tooltip text, bulleted lists, dialog body text, hyperlinked text, titles, and buttons containing a sentence. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| Invite your first seller | Invite your first seller. | +| Here you can invite and onboard new sellers | Here you can invite and onboard new sellers. | +| Collection deleted successfully | Collection deleted successfully! | +| Total captured orders within the selected period | Total captured orders within the selected period. | +| Learn more | Learn more. | +| Delete user | Delete user? | +| I agree and accept | I agree and accept. | + +### Use periods on multiple sentences; long or complex sentences, if it suits the context; or any sentence followed by a link. + +| Do ✅ | Don't ❌ | +| :---- | :---- | +| Words related to the product. They will be used in searches. Separate the words with commas ",". | Words related to the product. They will be used in searches. Separate the words with commas "," | +| You are using {current, number} out of {limit, number} available coupon slots. Remove some coupons to create more. Learn more | You are using {current, number} out of {limit, number} available coupon slots. Remove some coupons to create more Learn more | diff --git a/docs/en/user-interfaces/ui-focused-titles.md b/docs/en/user-interfaces/ui-focused-titles.md new file mode 100644 index 000000000..a9f3e3ff2 --- /dev/null +++ b/docs/en/user-interfaces/ui-focused-titles.md @@ -0,0 +1,91 @@ +--- +title: 'Titles' +id: ui0003 +status: PUBLISHED +createdAt: 2024-12-05T19:24:22.388Z +updatedAt: 2024-12-05T19:24:22.388Z +publishedAt: 2024-12-05T19:24:22.388Z +firstPublishedAt: 2024-12-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: titles +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: titles +--- + +### Titles consist of up to three words to name the content of a page or a specific section within it. This pattern is commonly used in components like Modals or Tabs. + +### General + +#### Use sentence case but capitalize proper nouns. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Give feedback
• Help Center | • Give Feedback
• Help center | + +#### Don't use punctuation, such as question marks or periods. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Page not found
• Delete user | • Page not found.
• Delete user? | + +#### Avoid using articles. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Add new seller | • Add a new seller | + +#### Don't use personal pronouns. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Application keys | • My application keys | + +#### Keep it as short as possible while still being descriptive enough. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Inventory
• Campaigns | • Inventory management
• Store promotional campaigns | + +#### Avoid redundancy, such as by omitting context present elsewhere. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Page title:
Products
• Titles inside page:
Products
Categories | • Page title:
Permissions
• Titles inside page:
Product permissions
Category permissions | + +#### Don't use a marketing tone of voice. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Search
• New product | • VTEX Intelligent Search
• Quickly create a product | + +### Specific + +### Page + +#### Reuse the same page title whenever possible, such as in the URL, title meta tag, and, when it applies, in a navigation entry. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Page title: Orders
• Title meta tag: Orders
• URL: /orders
• Navigation entry: Orders | • Page title: Orders
• Title meta tag: Orders listing
• URL: /all-orders
• Navigation entry: Store orders | + +#### In a form page, when an item is being edited, use the name of the item as the page title. When a new item is being created, use the word `New` followed by the item type. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Christmas discount
• New promotion | • Promotion
• Untitled promotion | + +#### In a listing page, use the type of item being listed as the page title. Include only nouns in the plural form and avoid adding an unnecessary prefix or suffix. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Product
• Orders | • All products
• Orders listing | + +### Modal + +#### In a modal with a form or actions, use an action label as the title. If the modal was triggered by action, prefer to repeat the verb of the action that triggered the modal. + +| Do ✅ | Don't ❌ | +| --------- | ------------ | +| • Delete shipping policy
• Create release | • Shipping policy
• Create | diff --git a/docs/en/user-interfaces/user-interfaces-test.md b/docs/en/user-interfaces/user-interfaces-test.md new file mode 100644 index 000000000..ac1e7917a --- /dev/null +++ b/docs/en/user-interfaces/user-interfaces-test.md @@ -0,0 +1,17 @@ +--- +title: 'user interfaces test file' +id: user-interfaces-test-file +status: PUBLISHED +createdAt: 2024-11-05T19:24:22.388Z +updatedAt: 2024-11-05T19:24:22.388Z +publishedAt: 2024-11-05T19:24:22.388Z +firstPublishedAt: 2024-11-05T19:24:22.388Z +contentType: trackArticle +productTeam: Localization +slugEN: user-interfaces-test-file +locale: en +trackId: 5PxyAgZrtiYlaYZBTlhJ2A +trackSlugEN: user-interfaces-test-file +--- + +This is a test file to check the connection between the documentation repository and the webpage repository. \ No newline at end of file diff --git a/images/en/capitalization.png b/images/en/capitalization.png new file mode 100644 index 000000000..8411731c0 Binary files /dev/null and b/images/en/capitalization.png differ diff --git a/images/en/how-to-open-a-pull-request.png b/images/en/how-to-open-a-pull-request.png new file mode 100644 index 000000000..15f748be7 Binary files /dev/null and b/images/en/how-to-open-a-pull-request.png differ diff --git a/images/en/how-to-submit-feedback.gif b/images/en/how-to-submit-feedback.gif new file mode 100644 index 000000000..0d152f22a Binary files /dev/null and b/images/en/how-to-submit-feedback.gif differ diff --git a/images/en/how-to-suggest-edits.gif b/images/en/how-to-suggest-edits.gif new file mode 100644 index 000000000..c2744158f Binary files /dev/null and b/images/en/how-to-suggest-edits.gif differ