diff --git a/assets/docs/images/tutorials/deploy-clusters/clusters_public-cloud_deploy-k8s-cluster_application.png b/assets/docs/images/tutorials/deploy-clusters/clusters_public-cloud_deploy-k8s-cluster_application.png index 08d7986433..c905c98f87 100644 Binary files a/assets/docs/images/tutorials/deploy-clusters/clusters_public-cloud_deploy-k8s-cluster_application.png and b/assets/docs/images/tutorials/deploy-clusters/clusters_public-cloud_deploy-k8s-cluster_application.png differ diff --git a/content/docs/04-clusters/01-public-cloud/01-aws/10-required-iam-policies.md b/content/docs/04-clusters/01-public-cloud/01-aws/10-required-iam-policies.md index 7a23ed335c..c3ff83cca6 100644 --- a/content/docs/04-clusters/01-public-cloud/01-aws/10-required-iam-policies.md +++ b/content/docs/04-clusters/01-public-cloud/01-aws/10-required-iam-policies.md @@ -471,7 +471,7 @@ If you plan to deploy host clusters to AWS EKS, make sure to attach the **Palett "iam:CreateOpenIDConnectProvider", "iam:DeleteOpenIDConnectProvider", "iam:ListOpenIDConnectProviders", - "iam:UpdateOpenIDConnectProviderThumbprint", + "iam:UpdateOpenIDConnectProviderThumbprint" ], "Resource": [ "*" diff --git a/content/docs/04-clusters/02-data-center/01-maas/15-create-manage-maas-clusters.md b/content/docs/04-clusters/02-data-center/01-maas/15-create-manage-maas-clusters.md index ec51e3cf8f..354d492f33 100644 --- a/content/docs/04-clusters/02-data-center/01-maas/15-create-manage-maas-clusters.md +++ b/content/docs/04-clusters/02-data-center/01-maas/15-create-manage-maas-clusters.md @@ -25,6 +25,10 @@ Palette supports creating and managing Kubernetes clusters deployed to a MAAS ac - A cluster profile for the MAAS environment. Review [Cluster Profiles](/cluster-profiles) for more information. + +- Verify that the required Operating System (OS) images you use in your cluster profiles are downloaded and available in your MAAS environment. Review the [How to use standard images](https://maas.io/docs/how-to-use-standard-images) for guidance on downloading OS images for MAAS. + + # Deploy a MAAS cluster To deploy a new MAAS cluster: @@ -118,18 +122,25 @@ The cluster status is updated to **Deleting** while cluster resources are being
-## Force Delete a Cluster -If a cluster is stuck in the Deletion state for a minimum of 15 minutes it becomes eligible for force deletion. You can force delete a cluster from the tenant and project admin scopes. To force delete a cluster, follow the same steps outlined in [Delete a MAAS Cluster](/clusters/data-center/maas/create-manage-maas-clusters#deleteamaascluster). After 15 minutes, a **Force Delete Cluster** option is available in the **Settings drop-down menu**. The drop-down menu will provide you with an estimated remaining duration before the force deletion becomes available. +# Upgrade a MAAS Cluster -
+Upgrade a MAAS cluster to enhance the performance and functionality of the cluster. To learn more about managing a MAAS cluster, refer to [Manage Clusters](https://docs.spectrocloud.com/clusters/cluster-management/cluster-updates). + +To protect your data, we recommend you create a backup of your MAAS cluster before proceeding with any upgrades or infrastructure changes. Review instructions provided in the [Backup and Restore](https://docs.spectrocloud.com/clusters/cluster-management/backup-restore). + +
-A force delete can result in Palette-provisioned resources being missed during the removal process. Verify that any MAAS machines associated with the cluster have been released. Failure to remove provisioned resources can result in unexpected costs. +Ensure that the Operating System (OS) image selected for your cluster are downloaded and available for your MAAS configuration to eliminate errors in Pallete. You can refer to the [How to use standard images](https://maas.io/docs/how-to-customise-images) guide for instructions on downloading OS images compatible with their respective MAAS environment. + + + + # Next Steps Now that you’ve deployed a MAAS cluster, you can start developing and deploying applications to your cluster. We recommend you review the Day-2 operations and become familiar with the cluster management tasks. Check out the [Manage Clusters](/clusters/cluster-management) documentation to learn more about Day-2 responsibilities. diff --git a/content/docs/04-clusters/03-edge/02-edge-configuration/35-installer-reference.md b/content/docs/04-clusters/03-edge/02-edge-configuration/35-installer-reference.md index 8d48506dac..eefa8ff29f 100644 --- a/content/docs/04-clusters/03-edge/02-edge-configuration/35-installer-reference.md +++ b/content/docs/04-clusters/03-edge/02-edge-configuration/35-installer-reference.md @@ -27,7 +27,6 @@ The Edge Installer is configured with a set of default values. | `PaletteEndpoint`| `api.console.spectrocloud.com`| The Palette API endpoint. | | `Prefix`| `edge`| The default prefix to apply to the unique identifier. | | `RegistrationURL`| `https://edge-registration-generic.vercel.app`| The URL that operators should use when registering the Edge host with Palette.| -| `installHarbor`| `false`| Set to `true` to enable the usage of a Harbor registry.| The default values assume you are installing the Edge host in an environment without a network proxy, do not require remote access to the Edge host, and are using Palette SaaS. If you have requirements different from the default values, you must provide the Edge Installer with additional information. diff --git a/content/docs/06-integrations.mdx b/content/docs/06-integrations.mdx index 2791944855..00ec051f60 100644 --- a/content/docs/06-integrations.mdx +++ b/content/docs/06-integrations.mdx @@ -22,6 +22,6 @@ When you create a cluster profile, you choose the type of pack you want to add: When you choose **Infrastructure** or **Add-on**, Palette presents only packs that provide functionality for the selected pack type. When you choose **Full**, Palette presents all the packs so you can build your cluster profile from the base layer up. To learn more about cluster profiles, check out the [Cluster Profiles](/cluster-profiles) guide. -To learn more about individual packs, use the search bar below to find a specific option. Alternatively, use the filter buttons to display available options. +To learn more about individual packs, use the search bar below to find a specific option. Alternatively, you can use the filter buttons to display available options. To learn about pack update and deprecation schedules, review [Maintenance Policy](/integrations/maintenance-policy). diff --git a/content/docs/06-integrations/00-kubernetes.md b/content/docs/06-integrations/00-kubernetes.md index 6bd28f23f5..3bf194434f 100644 --- a/content/docs/06-integrations/00-kubernetes.md +++ b/content/docs/06-integrations/00-kubernetes.md @@ -1,7 +1,7 @@ --- -title: "Kubernetes" -metaTitle: "Kubernetes in Palette" -metaDescription: "Kubernetes pack that deploys containers in Palette." +title: "Palette eXtended Kubernetes" +metaTitle: "Palette eXtended Kubernetes" +metaDescription: "Learn more about the Palette eXtended Kubernetes pack and how you can use it with your host clusters." hiddenFromNav: true type: "integration" category: ["kubernetes"] @@ -14,44 +14,35 @@ import InfoBox from 'shared/components/InfoBox'; import PointsOfInterest from 'shared/components/common/PointOfInterest'; import Tooltip from "shared/components/ui/Tooltip"; -# Kubernetes +# Palette eXtended Kubernetes -The Kubernetes pack defines the default properties that we use to deploy Kubernetes clusters. Most of the Kubernetes hardening standards that the Center for Internet Security (CIS) recommends are enabled by default. The Kubernetes pack supports most [cloud and data center infrastructure providers](/clusters). +The [Palette eXtended Kubernetes](/glossary-all#paletteextendedkubernetes(pxk)) (PXK) pack supports several [cloud and data center infrastructure providers](/clusters). This pack defines the default properties we use to deploy Kubernetes clusters and enables most of the Kubernetes hardening standards that the Center for Internet Security (CIS) recommends. -Spectro Cloud offers Cloud Native Computing Foundation (CNCF) Kubernetes as a core infrastructure pack in Palette. We release Kubernetes updates as follows: +We also support managed Kubernetes distributions for Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), and Tencent Kubernetes Engine (TKE). -
- -- Major versions are assessed based on the extent of changes. -- Minor versions are provided within eight weeks of a new Kubernetes release. -- Patch versions are provided within four weeks of a new Kubernetes release. - -In the period of time following a Kubernetes release, the Kubernetes pack undergoes rigorous vulnerability scans and penetration testing. +We offer PXK as a core pack in Palette. -A minor Kubernetes version will be deprecated in Palette when the Kubernetes community announces the version is entering End of Life (EOL). The deprecated version will remain in that state for three months and will be disabled after a quarter and deleted from Palette in the following quarter. +Review [Maintenance Policy](/integrations/maintenance-policy) to learn about pack update and deprecation schedules. -Below are the stages of deprecation: - -
+## What is PXK? -- **Deprecate**: When a pack is deprecated, Palette displays a warning. You will still be able to create new cluster profiles using the pack and launch clusters using existing profiles that contain the pack. +Palette eXtended Kubernetes (PXK) is a customized version of the open-source Cloud Native Computing Foundation (CNCF) distribution of Kubernetes. This Kubernetes version can be deployed through Palette to all major infrastructure providers, public cloud providers, and private data center providers. This is the default distribution when deploying a Kubernetes cluster through Palette. You have the option to choose other Kubernetes distributions, such as MicroK8s, Konvoy, and more, should you want to consume a different Kubernetes distribution. +PXK is different from the upstream open-source Kubernetes version primarily because of the carefully reviewed and applied hardening of the operating system (OS) and Kubernetes. The hardening ranges from removing unused kernel modules to using an OS configuration that follows industry best practices. Our custom Kubernetes configuration addresses common Kubernetes deployment security pitfalls and implements industry best practices. -- **Disable**: When a pack is disabled, you will no longer be allowed to create new cluster profiles using the pack. Palette displays a message informing you to cut over to the newer version of the pack. However, you can still deploy new clusters using existing profiles that contain the deprecated pack. +A benefit of Palette when used with PXK is the ability to apply different flavors of container storage interface (CSI) plugins and container network interface (CNI) plugins. Other open-source Kubernetes distributions, such as MicroK8s, RKE2, and K3s, come with a default CSI and CNI. Additional complexity and overhead are required from you to enable different interfaces. PXK supports the ability to select other interface plugins out of the box without any additional overhead or complexity needed from your side. - -- **Delete**: When a pack is deleted, you will not be able to create new cluster profiles using the pack or launch new clusters using the existing profiles that contain the pack. Palette displays a message informing you to cut over to the newer version of the pack. There is no disruption to existing cluster workloads and will continue to be functional. +There are no changes to the Kubernetes source code and we also follow the same versioning schema as the upstream open-source Kubernetes distribution.
- -For important guidelines on updating pack versions, review [Update the Pack Version](/cluster-profiles/task-update-profile#updatethepackversion). + +We also offer Palette eXtended Kubernetes Edge (PXK-E) for Edge deployments. Refer to the [PXK-E glossary definition](/glossary-all#paletteextendedkubernetesedge(pxk-e)) to learn more about PXK-E. - # Versions Supported diff --git a/content/docs/06-integrations/01-maintenance-policy.md b/content/docs/06-integrations/01-maintenance-policy.md new file mode 100644 index 0000000000..9e255b7c58 --- /dev/null +++ b/content/docs/06-integrations/01-maintenance-policy.md @@ -0,0 +1,177 @@ +--- +title: "Maintenance Policy" +metaTitle: "Packs Maintenance Policy" +metaDescription: "Learn about Palette pack update and deprecation schedules." +icon: "" +hideToC: false +fullWidth: true +hideToCSidebar: false +--- + +import {Content} from "shared/layouts/Default"; +import Tabs from "shared/components/ui/Tabs"; +import Packs from "shared/components/common/Integrations/Packs" +import AppTiers from "shared/components/common/Integrations/AppTiers" +import WarningBox from 'shared/components/WarningBox'; +import InfoBox from 'shared/components/InfoBox'; + + + +# Overview + +Palette supports two pack categories: *Core* and *Add-on*. Core packs, which we often source from third parties, are infrastructure related or have prominence in container-based environments. They create the layers in Palette profiles. Core packs are grouped as follows: + +- Kubernetes + +- Operating System (OS) + +- Container Network Interface (CNI) + +- Container Storage Interface (CSI) + + +Add-on packs provide additional functionality that you can add to your cluster profile and are grouped as follows: + +- Load Balancer + +- Ingress + +- Logging + +- Monitoring + +- Security + +- Authenticaiton + +- System Apps + + +Check out the [Packs List](/integrations) document, where you can use the filter buttons to display a list of Palette packs in each category and learn about the individual packs. + +
+ +## Pack Updates + +Packs undergo rigorous vulnerability scans and penetration testing before they become available in Palette. The following sections describe our update schedule for each core pack category. + +
+ +### Kubernetes Packs + +We provide Cloud Native Computing Foundation (CNCF) Kubernetes updates as follows: + +
+ +- **Major versions**: Assessed based on the extent of changes. + + +- **Minor versions**: Provided within eight weeks of a new Kubernetes release. + + +- **Patch versions**: Provided within four weeks of a new Kubernetes release. + + + +### OS Packs + +We provide Ubuntu LTS and CentOS updates for IaaS clusters as follows: + +
+ +- **Major versions** - Added within 8 weeks of release. + + +- **Patch and Minor versions**: Updated at runtime using Palette’s on-demand or scheduled OS upgrades and patch-on-boot capabilities. + + +### CNI Packs + +We provide CNI pack updates as follows: + +
+ +- **Major versions**: Assessed based on the extent of changes. + + +- **Minor version**: Added within 6 weeks of release. + + +- **Patch versions**: Added within 4 weeks of release. + + +### CSI Packs + +We provide CSI pack updates as follows: + +
+ +- **Major versions**: Assessed based on the extent of changes. + + +- **Minor version**: Added within 6 weeks of release. + + +- **Patch versions**: Added within 4 weeks of release. + + +### Add-on Packs + +We provide add-on pack updates as follows: + +
+ +- **Major versions**: Assessed based on the extent of changes. + + +- **Minor version**: Added within 6 weeks of release. + + +- **Patch versions**: Added within 4 weeks of release. + + +## Packs Deprecation + + + + + + +We deprecate and remove packs when a more stable version of the pack is available or when the underlying technology becomes obsolete. We deprecate a pack six months before deleting it. Post deprecation, you will still be able to create new cluster profiles using the pack and deploy clusters that use profiles containing the pack. Our Release Notes announce when a pack is deprecated and a replacement pack is available. + + +
+ + + + + +For important guidelines on updating pack versions, review [Update the Pack Version](/cluster-profiles/task-update-profile#updatethepackversion). + + + +### Kubernetes Packs + +A minor Kubernetes version is deprecated in Palette when the Kubernetes community announces the version is entering End of Life (EOL). + +
+ +### CNI / CSI / Add-on Packs + +Palette supports a minor version of CNI, CSI, and add-on packs until two newer versions are available. At that time, packs in these categories are deprecated. + + +
+ +
+ diff --git a/content/docs/17-glossary-all.md b/content/docs/17-glossary-all.md index dd2acfb199..2f842999e9 100644 --- a/content/docs/17-glossary-all.md +++ b/content/docs/17-glossary-all.md @@ -101,7 +101,7 @@ Palette eXtended Kubernetes (PXK) is a customized version of the open-source Clo PXK is different from the upstream open-source Kubernetes version primarily because of the carefully reviewed and applied hardening of the operating system (OS) and Kubernetes. The hardening ranges from removing unused kernel modules to using an OS configuration that follows industry best practices. Our custom Kubernetes configuration addresses common Kubernetes deployment security pitfalls and implements industry best practices. A benefit of Palette when used with PXK is the ability to apply different flavors of container storage interface (CSI) plugins and container network interface (CNI) plugins. -Other open-source Kubernetes distributions, such as MicroK8s, RKE2, and K3s, come with a default CSI and CNI. Additional complexity and overhead are required from you to enable different interface. PXK supports the ability to select other interface plugins out of the box without any additional overhead or complexity needed from your side. +Other open-source Kubernetes distributions, such as MicroK8s, RKE2, and K3s, come with a default CSI and CNI. Additional complexity and overhead are required from you to enable different interfaces. PXK supports the ability to select other interface plugins out of the box without any additional overhead or complexity needed from your side. There are no changes to the Kubernetes source code and we also follow the same versioning schema as the upstream open-source Kubernetes distribution. diff --git a/styleguide/Home.md b/styleguide/Home.md new file mode 100644 index 0000000000..0caac69e04 --- /dev/null +++ b/styleguide/Home.md @@ -0,0 +1,22 @@ +Welcome to the Spectro Cloud Style Guide. + +The [Spectro Cloud Style Guide](https://github.com/spectrocloud/librarium/wiki/Spectro-Cloud-Style-Guide) provides standards and guidelines for developing Spectro Cloud-related documentation in line with our brand, voice, and style. We believe in communicating effectively with all users and focus on keeping it simple, concise, and friendly. + +To ensure all documentation reflects our voice and style, we recommend you start by reviewing the [Style Guide](https://github.com/spectrocloud/librarium/wiki/Spectro-Cloud-Style-Guide). Use the [Spectro Cloud Style Guide](https://github.com/spectrocloud/librarium/wiki/Spectro-Cloud-Style-Guide) to effectively translate our preferred communication approach into impactful documentation, ensuring that your content resonates with our audience and encourages interaction. + + +All of our documentation is expected to follow a set of standard templates. The [Content Layout](https://github.com/spectrocloud/librarium/wiki/Content-Layout) resource explains each of our writing artifacts in greater detail. + +The following list provides a high-level overview of the writing artifacts we use in our documentation. +* [How-to Layout](https://github.com/spectrocloud/librarium/wiki/How-to-Layout) - A how-to’s purpose is to help the user perform a particular task correctly. Refer to the [How-to Layout](https://github.com/spectrocloud/librarium/wiki/How-to-Layout) to use the layout and learn how to structure a how-to guide. + +* [Packs Layout](https://github.com/spectrocloud/librarium/wiki/Packs-Layout) - The Packs Layout provides an overview and guidelines for how to organize and structure a pack documentation page. Refer to the [Packs Layout](https://github.com/spectrocloud/librarium/wiki/Packs-Layout) guide to learn more. + +* [Troubleshooting Layout](https://github.com/spectrocloud/librarium/wiki/Troubleshooting-Layout) - All Spectro Cloud troubleshooting guides are expected to have the same look and feel. The guide must also feel familiar to the reader. Therefore, all troubleshooting guides must follow the layout standard described. Refer to the [Troubleshooting Layout](https://github.com/spectrocloud/librarium/wiki/Troubleshooting-Layout) to use the troubleshooting layout. + + + +* [Tutorial Layout](https://github.com/spectrocloud/librarium/wiki/Tutorial-Layout) - Our tutorials are written and structured in a specific manner and style. Refer to the [Tutorial Layout](https://github.com/spectrocloud/librarium/wiki/Tutorial-Layout) guide to learn how to structure a tutorial for Spectro Cloud documentation. + +Refer to the [Spectro Cloud Word List](https://github.com/spectrocloud/librarium/wiki/Spectro-Cloud-Word-List) to learn more about the choices we have made when it comes to certain words and their usage in our writing. + diff --git a/styleguide/content-layout.md b/styleguide/content-layout.md new file mode 100644 index 0000000000..17b3907836 --- /dev/null +++ b/styleguide/content-layout.md @@ -0,0 +1,53 @@ +After you have reviewed the [Spectro Cloud Style Guide](https://github.com/spectrocloud/librarium/wiki/Spectro-Cloud-Style-Guide), the next step is planning and designing your content. + + +Before you contribute, take some time and become familiar with the content type you are writing. If you have any questions, send us an email at [spectro-docs@spectrocloud.com](spectro-docs@spectrocloud.com). + +# Table of Contents + +[How to Layout](#how-to-layout) + +[Packs Layout](#packs-layout) + +[Troubleshooting Layout](#troubleshooting-layout) + +[Tutorial Layout](#tutorial-layout) + + +## [How to Layout](https://github.com/spectrocloud/librarium/wiki/How-to-Layout) + +How-to guides help users perform a particular task or set of actions. A well-written how-to guide provides the following benefits: + +- Addresses knowledge-sharing issues. + +- Eliminates delays caused by knowledge gaps. + +- Prevents user errors due to clear guidance. + +- Reduces time spent searching for task assistance. + +The [How-to Layout](https://github.com/spectrocloud/librarium/wiki/How-to-Layout) page teaches you how to structure a how-to guide in accordance with our style and preferred teaching approach. + + +## [Packs Layout](https://github.com/spectrocloud/librarium/wiki/Packs-Layout) + +Before creating your a Pack documentation page, start by reviewing the [Packs Layout](https://github.com/spectrocloud/librarium/wiki/Packs-Layout) page. Documenting Packs can be challenging due to their complex nature, involving multiple components and dependencies. However, this documentation is immensely valuable to our users. Well-documented Packs enable users to understand how to use the pack better, resulting in an improved user experience when consuming the pack. + +The [Packs Layout](https://github.com/spectrocloud/librarium/wiki/Packs-Layout) page guides you to structure a pack documentation page to ensure consistency with the rest of our documentation. + + + + +## [Troubleshooting Layout](https://github.com/spectrocloud/librarium/wiki/Troubleshooting-Layout) + + +A troubleshooting guide is a well-organized collection of guidelines that offer strategies to identify, diagnose, and resolve a wide range of commonly occurring and unpredictable problems. A well-written troubleshooting guide can be an invaluable reference tool. Its purpose is to empower users to independently resolve issues, and minimize downtime. + + +Learn how to structure a troubleshooting guide by reviewing the [Troubleshooting Layout](https://github.com/spectrocloud/librarium/wiki/Troubleshooting-Layout) page. + +## [Tutorial Layout](https://github.com/spectrocloud/librarium/wiki/Tutorial-Layout) + +A tutorial guides the users through a series of actions or steps. Unlike a how-to guide, a tutorial often provides a starter code and focuses on explaining the why and how. A tutorial should provide clear instructions and guide the user in learning new skills and completing the milestones established for the tutorial. + +We follow a specific style and teaching approach for all Spectro Cloud tutorials. Review the [Tutorial Layout](https://github.com/spectrocloud/librarium/wiki/Tutorial-Layout) page to learn how to structure a tutorial in accordance with our standards. diff --git a/styleguide/how-to.md b/styleguide/how-to.md new file mode 100644 index 0000000000..a4530fb403 --- /dev/null +++ b/styleguide/how-to.md @@ -0,0 +1,103 @@ +# How-To-Guide + +All Spectro Cloud How-Tos are expected to have the same look and feel. The How-To text and voice must adhere to the Spectro Cloud [style guide](https://github.com/rahulhazra97/Documentation-Guide/wiki/Spectro-Cloud-Style-Guide) for a universal look and feel. The how-tos layout must also feel familiar to the reader; therefore, all how-tos must follow the layout standard described on this page. + + + +> ℹ️ Tutorial vs How-to - What is the difference?
+> * A how-to directs the reader on how to complete the work without diving into specifics. A tutorial dives into the specifics and explains concepts in great detail. +> * A how-to’s purpose is to help the user perform a particular task correctly. A tutorial will also enable the feature and showcase its functionality through a demo application. +> * A how-to’s primary intent is to ensure the successful enablement of a specific action. A tutorial focuses on the learning experience and provides the reader understanding of the concepts of how and why. +> * A how-to is intended to be executed in the reader’s environment. A tutorial occurs in a learning environment where software and other dependencies are tightly controlled. + +# Table of Contents + + [Markdown Layout](#markdown-layout) + + [Section Breakdown](#section-breakdown) + + + +## Markdown Layout + +The following is a high-level overview of the markdown structure that all how-tos should contain. Make a note of the markdown heading sizes. + +``` +# Title + +# Prerequisites + +# Enablement + +1. Action 1 ... + +... + +... + +N. Action N + +# Validate +``` + +> :warning: If you find yourself in a situation where you have multiple smaller how-to’s in a single page, then reduce the heading sizes by one for all other headings except the title. Example:
+> <# Open a Jar>
+> <## ….>
+> <# Remove a Jar>
+> <## ….>
+ +## Section Breakdown + + + + + + + + + + + + + + + + + + + + + +
Section Description
Title + +A minimal overview of the feature. This part of the text should link to a dedicated reference page of the feature. + +
Prerequisites + +List out the required software version or hardware the practitioner must have installed and available to enable the feature. + +
Enablement + +This section contains the sequential steps required to enable the feature. The steps may be console actions, commands, or scrips the user must invoke. The reader should be able to follow the steps sequentially and successfully enable the feature. As the author, you can change the title to something that makes sense. Just ensure you follow the style guide for headings. You can use smaller headings in between to help break up the topic. Example:
+```terraform + # Enablement + Blah Blab Blah + + ## Find a Jar + .1 Drive to store + ... + .. + + ## Select a Jar + 1. Review ingriendies labels ... + ... + ... + + # Validate +``` + +
Validate + +This section provides the user information on validating that the feature is enabled correctly. This may be a command the user invokes, a console page they visit, an entry in a log, and so on. + +
diff --git a/styleguide/packs-layout.md b/styleguide/packs-layout.md new file mode 100644 index 0000000000..d4c95f6688 --- /dev/null +++ b/styleguide/packs-layout.md @@ -0,0 +1,146 @@ +# Packs Layout + +All Spectro Cloud Packs docs are expected to have the same look and feel. The text and voice must adhere to the Spectro Cloud [style guide](https://github.com/rahulhazra97/Documentation-Guide/wiki/Spectro-Cloud-Style-Guide) for a universal look and feel. The packs doc layout must also feel familiar to the reader and follow the layout standard described on this page. + +A Packs doc is no different than a regular documentation page, except that it includes supported versions and a References section that links to external sources instead of a Resources section. + +# Table of Contents + + [Markdown Layout](#markdown-layout) + + [Section Breakdown](#section-breakdown) + + [Examples](#examples) + +## Markdown Layout + +The following is a high-level overview of the markdown structure that packs docs should contain. Note the markdown heading sizes. +Since there are several packs categories, headings in green may vary depending on the pack. + +``` +# Title + + +# Versions Supported + +< Tabs for multiple versions > + +< Bullet for single version > + + +For each version tab: Prerequisites, Parameters, Usage + + +## Prerequisites + + +## Parameters + + +## Usage + + +# Troubleshooting + + +# Terraform + + +# References + +``` +## Section Breakdown + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Section Description
Title + +A minimal feature overview.
In pack docs with a Components section, remove the heading and include the components list here. This is typically a list of resources and integration adds, deploys, or creates, such as a Controller, Ingress or Egress Gateway, or UI. Only a few of the packs docs have this section.
If a pack adds only one resource, use a sentence to say what resource the pack adds. + +
Versions Supported + +Each numbered version tab has these headings: +* Prerequisites +* Parameters +* Usage +
If several versions are supported, list them in tabs with the latest version at left. Label tabs as follows with a **.x** extension. Do not list specific versions. For example: +
![image](https://github.com/rahulhazra97/Documentation-Guide/assets/126905240/496fc564-0eab-4b06-b614-deb681024a32) + +
Prerequisites + +List the required software version or hardware the user is required to have installed and available to integrate the pack. + +
Parameters + +:warning: Most times, parameters will apply, but if they don’t, then omit this section.

If applicable, list and describe only the most commonly used parameters, especially if there are 10 or more that might apply. Include an introductory sentence to clarify these are commonly used parameters:
“The table lists the most commonly used parameters you can configure when adding this pack.”

If using a table to list parameters, include the following columns:

Columns: **Parameter**, **Description**.

You may include a **Required** column if the user must modify the parameter. A required column may not apply to all Packs. The same guidance required applies to a column for the **Default** value of a parameter. + +
Usage + +Describe the common use case and an example if applicable. Include any customization information that may apply. This section should give the reader an idea of how to use the pack. This is separate from informing the user how to add the pack. + +
Troubleshooting + +:warning: If no troubleshooting steps are available then omit this section.

This section contains troubleshooting steps pertaining to the respective Pack. + +
Terraform + +^ Extra blank line above! +```terraform + data "spectrocloud_registry" "public_registry" { + name = "Public Repo" +} + +data "spectrocloud_pack_simple" "spectro-proxy" { + name = "spectro-proxy" + version = "1.2.0" + type = "operator-instance" + registry_uid = data.spectrocloud_registry.public_registry.id +} +``` + + +
Reference + +List at least one external source users can reference to learn more about the pack they are integrating. References must be in standard MarkDown link format [_link_label_](_https://link_). + +
+ +## Examples +Use the following examples to better understand how to structure a Packs page. +* [Kubernetes](https://docs.spectrocloud.com/integrations/kubernetes) - No Defaults and Required column for parameters. +* [Prometheus Agent](https://docs.spectrocloud.com/integrations/prometheus-agent) - Only a single required parameter +* [Spectro Kubernetes Dashboard](https://docs.spectrocloud.com/integrations/spectro-k8s-dashboard) - Default values for parameters diff --git a/styleguide/sidebar.md b/styleguide/sidebar.md new file mode 100644 index 0000000000..f6328b25fb --- /dev/null +++ b/styleguide/sidebar.md @@ -0,0 +1,18 @@ + +## [Home](https://github.com/spectrocloud/librarium/wiki) + +## [Spectro Cloud Style Guide](https://github.com/spectrocloud/librarium/wiki/Spectro-Cloud-Style-Guide) + +## [Content Layout](https://github.com/spectrocloud/librarium/wiki/Content-Layout) + +- ### [How-to Layout](https://github.com/spectrocloud/librarium/wiki/How-to-Layout) + +- ### [Packs Layout](https://github.com/spectrocloud/librarium/wiki/Packs-Layout) + +- ### [Troubleshooting Layout](https://github.com/spectrocloud/librarium/wiki/Troubleshooting-Layout) + +- ### [Tutorial Layout](https://github.com/spectrocloud/librarium/wiki/Tutorial-Layout) + +> - [Tutorial Plan Template](https://github.com/spectrocloud/librarium/wiki/Tutorial-Plan-Template) + +## [Spectro Cloud Word List](https://github.com/spectrocloud/librarium/wiki/Spectro-Cloud-Word-List) \ No newline at end of file diff --git a/styleguide/spectro-cloud-style-guide.md b/styleguide/spectro-cloud-style-guide.md new file mode 100644 index 0000000000..a184e087bb --- /dev/null +++ b/styleguide/spectro-cloud-style-guide.md @@ -0,0 +1,600 @@ + +# Spectro Cloud Style Guide + +The Spectro Cloud style guide provides standards and guidelines for developing Spectro Cloud-related documentation. The style guide will act as a tool to ensure that the content produced reflects our sense of style and voice. + + + +# Table of Contents + +[About this guide](#about-this-guide) + +[SpectroCloud Style and Voice](#spectrocloud-style-and-voice) + - [Simplified English](#simplified-english) + - [SpectroCloud Voice](#spectrocloud-voice) + - [Active voice](#active-voice) + - [Passive voice](#passive-voice) + +[Accessibility and Inclusion](#accessibility-and-inclusion) + +- [Diverse and Inclusive](#diverse-and-inclusive) +- [Simplicity Assumption](#simplicity-assumption) +- [Gender](#gender) +- [Albeist Language](#ableist-language) + +[Content Format](#content-format) + +- [Headings](#headings) +- [Headline Style](#headline-style) +- [Numbers](#numbers) +- [Tables](#tables) +- [UI Components](#ui-components) +- [Resources List](#resources-list) +- [Metadata](#metadata) +- [Directional Language](#directional-language) +- [InfoBox](#infobox) +- [Future features](#future-features) + +[Language](#language) + +- [Nouns and Pronouns](#nouns-and-pronouns) +- [Prepositions](#prepositions) +- [Present tense](#present-tense) +- [Person](#person) + +[Links](#links) + +- [Cross-references](#cross-references) +- [External URLs](#external-urls) +- [Slash](#slash) + +[Punctuation and Grammar](#punctuation-and-grammar) + +- [Capitalization](#capitalization) +- [Period, Exclamation Mark, and Question Mark](#period-exclamation-mark-and-question-mark) +- [Colon and Semicolon](#colon-and-semicolon) + +[UI Elements (naming)](#ui-elements-naming) + +- [Commands and Parameters](#commands-and-parameters) +- [Command Output](#command-output) +- [Parameters](#parameters) + + +## About this guide + +The Spectro Cloud style guide is designed to guide you to create focused, clean and impactful Spectro Cloud content the best way you can. Everyone across Spectro Cloud can use this guide to help reflect our values in their content’s approach and tone. + +### SpectroCloud Style and Voice + +Our brand style and voice reflect what we say and how we say it. We believe in simple, to-the-point, and friendly communication in our documentation. + +### Simplified English + +Use simple English in Spectro Cloud material unless explicitly stated otherwise in this guide. + + +More importantly, simple language helps the reader retain information and more readily understand concepts. Feel free to review the [simplified English](https://www.simplifiedenglish.net/simplified-english/) resource to understand better how simplified language improves technical documentation. + +| Good ✅ | Bad ❌ | +|--------------------------------------------------------------------------|----------------------------------------------------------------------------------| +| The core Kubernetes API is flexible and can also be extended to support custom resources. | The interior Kubernetes API is malleable and provides the capability for consumers to extended custom logic and inject custom logical resources. | +| Choose a node to be the cluster master node. | Designate a node to be the cluster master node. | +| Drain the node before a version upgrade. | It is essential to drain the node prior to a version upgrade. | + +### SpectroCloud Voice + +Write in a simple voice. We explain our process and actions with simple messages and to the point. We want our Spectro Cloud content to be: + +- Simple: For all users to understand it. + +- Focused and concise: For all users to be encouraged to interact with it. + +- Friendly and accessible: For all users to engage with it. + +Here are some tips to implement in your content: + +- Break down complex concepts into concise, bite-size content. + +- Use a conversational tone to create more engaging content. + +- Address the user as “you” to personalize the content. + +- Include practical tips and actionable information to build trust. + +- Create content that is needed at the time. + + +### Active voice + +Use the active voice whenever possible. The active voice is usually more direct and vigorous than the passive. When you write a sentence in the active voice, it is also usually shorter than in the passive voice. +Address the user when creating text content. Use the noun, you. Use, we, when providing the user with recommendations. We want to take ownership of our guidance, so avoid hiding using “it is recommended.” + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|-----------------------------------------------------------------| +| Use the kubectl cli to create a namespace titled “mgmt”. | The Kubectl CLI can be used to create namespaces titled “mgmt” | +| Prior to upgrading, ensure you have carefully reviewed the release notes for deprecation notices. | Release notes should be carefully verified for deprecation notices prior to an upgrade. | +|We recommended deploying Palette Enterprise in a highly-available configuration of at least three nodes. | It is recommended to deploy Palette Enterprise in a highly-available configuration of at least three nodes. | + +### Passive voice + + +Passive voice is a good fit when the agent or user performs an obvious, unimportant, or unknown action. Passive voice can also be used when you wish to postpone mentioning the agent until the last part of the sentence or avoid mentioning the agent. The passive voice is effective in these situations because it highlights the action and what is acted upon rather than the agent acting. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|-----------------------------------------------------------------| +| The dispatcher is notifying police that three prisoners have escaped. | Police are being notified that three prisoners have escaped. | +| Surgeons successfully performed a new experimental liver-transplant operation yesterday. | A new experimental liver-transplant operation was performed successfully yesterday. | +|In this tutorial, you learned how Palette allows operators to manage Kubernetes environments easily. | The tutorial explained how Pallete can be used easily to manage Kubernetes environments. | + + + +## Accessibility and Inclusion + +SpectroCloud content is built for people. This section overviews the accessibility and inclusion guidelines that matter when creating content. + +### Diverse and Inclusive + +Try to use diverse names, ages, and locations in examples. As a U.S.-based company, avoid only using Western locations and names. The Google Style guide has a great list of [common international names](https://developers.google.com/style/examples#names). + +| Good ✅ | Bad ❌ | +|------------------------------------------------------------------------------|------------------------------------------------------------------------------| +| The NOC-UI displays three active clusters. The following example displays active two clusters available in eastern Asia and another cluster in central Europe. | The NOC-UI displays three active clusters. The following image displays three active clusters in North America’s west and eastern regions. | +| Lee and Raha are both experienced engineers that fit the decision-maker persona. | John and Dave are both experienced engineers that fit the decision-maker persona. | + +### Simplicity Assumption + + +Our technology and workflows are complicated. Yes, our product improves the experience and greatly reduces the challenges encountered with Kubernetes. However, at the end of the day, these are complicated workflows. Avoid injecting assumptions into the text. Readers find it frustrating to read the documentation that states an action or set of actions is easy. Show compassion to the reader and make it “easy” by providing clear and concise guidance. Omit the subjective terms. + +| Good ✅ | Bad ❌ | +|------------------------------------------------------------------------------|------------------------------------------------------------------------------| +| Deploy the container in a few steps. | Deploy the container in a few simple steps. | +| Palette reduces the overhead and common challenges encountered when using Kubernetes. | Palette makes Kubernetes easy to use. | + +### Gender + +Use gender-neutral pronouns. Avoid the following nouns he, him, his, she, or her as gender-neutral pronouns. The same applies to he/she or (s)he or other such punctuational approaches. Use the singular they. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| In previous outages, one of the operators followed best practices. | In previous outages, one of the operators did not follow best practices. | + +### Ableist language + +Don't use ableist language. This avoids biases and harm when discussing disability and accessibility. Ableist language includes words or phrases such as crazy, insane, blind to or blind eye to, cripple, dumb, and others. This also includes action verbs with physical traits like jump and run. Choose alternative words depending on the context. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|-----------------------------------------------------------------| +| Review all the active containers. | See if all the containers are running. | +| Navigate to the tab titled, Settings. | Jump to the next tab. | +| Issue the command kubectl get pods. | Run the command kubectl get pods. | + + +## Content Format + +Your content format defines how you translate the brand style and voice in your content. Create responsive content assuming your content can be refigured based on the user's device. This section outlines the guidelines to help you structure your content and follow a clean formatting style theme. + +### Headings + + +The heading styles referenced are as follows: + +Avoid using an acronym for the first time in a title or heading unless it is a keyword you need to place in the title or heading for SEO. If the first use of the acronym is in a title or heading, introduce the acronym (in parentheses, following the spelt-out term) in the following body text. Aim for descriptive headings and titles to help users navigate the page. From a user perspective, Jumping between pages and sections of a page is easier if the headings and titles are unique. + +- If the heading is more in line with a task, start with the plain form of the task’s base form. + + +- If the heading is conceptual or non-task based, start with a noun. Avoid using a noun that starts with an -ing. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|-----------------------------------------------------------------| +| Deploy the Infrastructure. | Deploying IaC. | +| Migration to Palette. | Migrating to Palette tab. | +| Introduction to Cluster Monitoring. | Cluster Monitoring. | + +### Headline Style + +Use title case for headings. Below are some helpful tips. + + + - Capitalize the first and last words, nouns, pronouns, verbs, adjectives, adverbs, and subordinating conjunctions (if, because, as, that, and so on). + + + - Don't capitalize articles (a, an, the), coordinating conjunctions (and, but, or, nor), the "to" in an infinitive, and prepositions (with, to, for, in, from). + + +- For hyphenated words, capitalize the first and subsequent elements unless they are articles, prepositions, and coordinating conjunctions. The following are examples: + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|-----------------------------------------------------------------| +| Deploy a Pack Registry Server. | Deploying A Pack Registry Server. | +| Access Audit Logs. | Accessing audit logs | +| Quick Start with Palette App Mode. | Quick start with Palette app mode | + +### Numbers + +In the text, spell out single-digit numbers (zero through nine) and use numerals for 10 or greater. The exception is when an action is unimportant, unknown, or hard to identify. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|-----------------------------------------------------------------| +| The Kubernetes control plane should have at least three nodes if configured to be highly available. | The Kubernetes control plane should have at least 3 nodes if configured to be highly-available. | +| First, drain the worker nodes. | 1st drain the worker nodes.logs | +| Two-fifths of the log report contains decipherable content. | 3/5 of the log report contains decipherable content.mode | + + +### Tables + +Tables make complex information easier to understand by presenting it clearly. + +All table headings should be in bold. + +| Tables are useful for | Examples | +|---------------------------------|-----------------------------------------------------------------| +| Data or values | Text formats and their associated HTML codes. | +| Simple instructions| User interface actions and their associated keyboard shortcuts. | +| Categories of things with examples | SKUs and the products they include. | +| Collections of things with two or more attributes| Event dates with times and locations.| +| Differentiation | A table can often display differantion easier than it would be to use words. | + +### UI Components + + +For a list of available UI components refer to the documentation’s repository README. +Avoid the following behaviors when writing documentation content. + +| Component | Behavior | +|---------------------------|----------------------------------------------------------------------------------------------------------------------------------| +| Tooltip | Avoid using tooltips inline with the text. The recommendation is to use an info box if it makes sense or explain the concept. Alternatively, if the definition is available in the glossary page then link to the definition. | +| Info box and warning box | Avoid overusing info boxes and warning boxes. They have the potential to distract the reader and generate a sense of information overload. Use them sparingly. | + +### Resources list + + +List links to other documents and guides in a bullet list in the last section of your document. The title is a Level 1 heading. Include two lines between each item. + +**# Resources** + +- [VM Management Packs and Profiles](/vm-management/vm-packs-profiles) + +- [Spectro VM Dashboard](/vm-management/vm-packs-profiles/vm-dashboard) + +- [Create Spectro VM Dashboard Profile](/vm-management/vm-packs-profiles/create-vm-dashboard-profile) + +- [Enable Spectro VM Dashboard](/vm-management/vm-packs-profiles/enable-vm-dashboard) + +- [Create and Manage VMs](/vm-management/create-manage-vm) + +- [Deploy VM from a Template](/vm-management/create-manage-vm/standard-vm-operations/deploy-vm-from-template) + +- [Create a VM Template](/vm-management/create-manage-vm/create-vm-template) + +- [Standard VM Operations](/vm-management/create-manage-vm/standard-vm-operations) + +- [VM Roles and Permissions](/vm-management/vm-roles-permissions) + + +### Metadata + + +End the metaDescription with a period. + +``` +title: "Migrate Cluster to Enterprise Mode" + +metaTitle: "Migrate Cluster to Enterprise Mode" + +metaDescription: "Migrate Cluster to Enterprise Mode." +``` + +### Directional Language + + +Avoid directing the user to previous parts of the document, if possible. Ideally, the user should be directed to content following the text. By avoiding forcing the reader to scroll back, you improve the user experience. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| The following diagram displays the application architecture for this tutorial. | As seen in the diagram above, the application architecture is hosted on AWS. | + +### Infobox + +Use the info box to help users save an extra step of finding related information. Include relevant details directly alongside your content to add clarity. Remember, the goal is to conveniently present users with all necessary information within the infobox, minimizing the need to navigate back and forth between different sections. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| This pack can be combined with the Kubernetes dashboard pack to expose the Kubernetes dashboard. Check out the Enable Kubernetes Dashboard guide to learn more about exposing the Kubernetes dashboard. | To learn more about exposing the Kubernetes dashboard, check out the Enable Kubernetes Dashboard guide. | + +### Emoticon + + +Do not use emoticons in headlines or text. Emoticons are great for conveying emotions and making the text more welcoming, but at the cost of reducing the sense of the formality of the text. Our technical documentation is a place that all customers should trust. As a result, we want to convey as much professionalism as possible so that the text and its content are highly trusted. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| In this tutorial, you will understand how to migrate Kubernetes clusters to Palette’s management plane. | In this tutorial you will gain a basic understanding of how to migrate Kubernetes clusters to Palette’s management plane | + +### Future Features + + +Avoid documenting features, products, or behaviours that are currently unavailable. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| MagicProduct supports JSON input files. | MagicProduct supports JSON input files. In future releases, YAML file support will be added. | + + +## Language + +This section guides you to your content using easy and simple-to-understand language. + +### Nouns and Pronouns + +To use nouns, see [Capitalization](#capitalization). Use pronouns to clearly refer to the noun it’s replacing (its antecedent) to avoid ambiguity and confusion. Use gender-neutral pronouns to accommodate all users. See [Gender](#gender), to learn how more about gender-neutral pronouns. Use personal pronouns to offer a friendly tone. To learn more about using pronouns, see [Person](#person). Use relative pronouns: that, which, or who. + +### Prepositions + +Use the preposition to convey the notion of an enclosed space surrounded or closed off on all sides. + +- Do something in a dialog box. + +- Do something in a pane. + +- Enter something in a window. + +- Do something in command mode. +In these examples, a dialog box, a pane, a window, and a command mode represent enclosed spaces within which users interact. + +Use the preposition on to convey the notion of being on a surface of an entity. + +- Do something on a page. + +- Enter something on a worksheet. + +### Present tense + +Users read documentation to perform tasks or gather information. For users, these activities take place in their present, so the present tense is proper in most cases. Additionally, the present tense is easier to read than the past or future tense. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| A common container orchestration platform used in the industry is Kubernetes. | A common container orchestration platform that will be used in the industry is kubernetes. | + +Use future tense only when you emphasize that something will occur later (from the users' perspective). To quickly find and remove instances of future tense, search for will. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| The following steps will guide you on how to create a cluster profile for Edge. | The following steps guide you on how to create a cluster profile for Edge. | + +### Person + +Use second-person pronouns you, your to convey friendliness and human touch to the users. Addressing the user as you keeps the focus on them. It implies a supportive tone. If the discussion is about product UI, use second person pronouns as You can to help the user feel they have a choice to make. + + Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|-----------------------------------------------------------------| +| The following steps will guide you on how to create a cluster profile for Edge. | The following steps will guide us on how to create a cluster profile for Edge. | +| You can tailor your OS to your specific needs, ensuring your clusters perform optimally and meet your organization's unique requirements. | We can tailor our OS to our specific needs, ensuring our clusters perform optimally and meet our organization's unique requirements. | +| Alternatively, use the filter buttons to display available options. | Alternatively, you can use the filter buttons to display available options. | + +Be careful when using the following first-person pronouns: we, us, or our. If your content focuses on Spectro Cloud as the speaker, you can address the user in the first-person plural. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| Our style guide believes in simple and crisp writing. | The following steps will guide us on how to create a cluster profile for Edge. | +| To avoid this issue, we recommend that you authenticate with the Docker registry before pulling images, especially if you are pulling from a private registry. | To avoid this issue, you should authenticate with the Docker registry before pulling images, especially if you are pulling from a private registry. + +### Acronyms + +Use title case when defining an acronym. Use the same rules that apply to headline styles. Some acronyms are in nature written in a camel case. Example: IaaS, kCh, SaaS. + +Although some acronyms are widely understood and preferred to the spelt-out term, others are not well known or are familiar only to a specific group of customers. Define the acronym first. + +The exception is when an acronym will appear only once in your content. Spell out the term. Don't introduce it in parentheses after the spelt-out version. If the spelt-out term and acronym are needed for metadata, then it is okay to use both. + +| Good ✅ | Bad ❌ | +|--------------------|----------------------| +| Boot the Virtual Machine (VM). | Boot the virtual machine (VM). | +| Boot all the Virtual Machines (VMs). | Boot all the virtual machine (VMs). | +| This is called Infrastructure as a Service (IaaS). | This is called infrastructure as a service (IaaS). | +| Dynamic-Link Library (DLL). | dynamic-link library (DLL). | + +## Links + +Use links to point to a single source of truth to explain why your information links to it. Generally, practice ensuring that the links remain functional and universally accessible to the users. + +### Cross-references +In general, cross-references are links that lead to extra information. Try to offer assistance within the current context whenever feasible rather than redirect to external sources. +For example, if the information is short and easily explained, it's better to include it directly instead of using a link. + +- Log in to **Palette** as a tenant admin. + +- To learn how to install Palette using the Helm Chart, refer to **Helm Chart Mode**. + + +### External URLs + +When readers are assumed to have some prior knowledge about third-party standards or software, provide an external link. Ensure any external sites you link to are updated, reliable, and relevant within the context. + +Link to the most relevant heading so users can have easier access. Test all the links and remove any locale-specific information before publishing your document. Ensure that the links remain functional and universally accessible to readers. Avoid unnecessary redirects to maintain a smooth reading experience. + +Examples: + +- An active [MAAS API key](https://maas.io/docs/api-authentication-reference) which can be generated in the MAAS web console. + +- Enable [HTTP Event Collector (HEC)](https://www.outcoldsolutions.com/docs/monitoring-kubernetes/v5/installation/#enable-http-event-collector-in-splunk) in Splunk. + +- Refer to the [Prometheus Operational aspects](https://prometheus.io/docs/prometheus/latest/storage/#operational-aspects) documentation for additional guidance. + +### Slash + +We try to avoid using slashes. If required, use forward slashes ( / ) to to imply a combination or to indicate a file path. + +Use backslashes ( \ ) to list URLs. Omit `http://` unless the URL does not begin with `www` and any trailing slashes at the end of the URL unless the URL requires it. Use `http://` in reference links as required. + +Example: +https://console.spectrocloud.com + + +## Punctuation and Grammar + + +Use punctuation and grammar style conventions to localize your content into consistent information. Generally, use punctuation judiciously to preserve the content’s meaning, using it only when necessary. Tailor your grammar style to reflect the mood and personality to build engaging content for the user. + +### Capitalization + +Capitalize the first word and all proper nouns, such as product names. To learn more about proper nouns, see [Nouns and Pronouns](#nouns-and-pronouns). + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------| +| A common container orchestration platform used in the industry is Kubernetes. | a common container orchestration platform used in the industry is kubernetes. | +| Navigate to the Pallete console. | Navigate to the pallete console. | + +Don’t capitalize common nouns unless required. + +- Kubernetes is an open-source container orchestration platform. + + +- Kubectl allows you to connect to, configure and work with your clusters through the command line. + + +### Period, Exclamation Mark, and Question Mark + + +Use a period (.) at the end of every sentence. Do not use periods at the end of headings, headlines, UI titles, or UI texts. Put one space after a period. If a sentence includes a title, do not use a period at the title end, but if the title has a question mark ( ? ) or an exclamation mark ( ! ), you should include it. Avoid exclamation marks unless required. + +Examples: + +- Review the Network Address Translation (NATS) parameters guide to learn more. + +- What is Palette? + +- Refer to the What is Palette? section. + +### Colon and Semicolon + +Use a colon when you want to introduce a list. For instance, listing your favourite fruits, you might write, "Make sure you bring the items Rita requested to the party: soda, board games, and a side dish. When in doubt, default to a period and start a new sentence. + +Remember, the sentence before a colon should always be a complete thought. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------------------------|------------------------------------------------------------------------------| +| Common use cases for enabling authentication: | Common use cases for enabling authentication: | +| - Prevent others from accessing other users' resources. | Prevent others from accessing other users resources. | +| - Prevent abuse or spam from those not part of the community. | Prevent abuse or spam from those not part of the community. | +| | | +| This means that you may never need to manipulate ReplicaSet objects.| This actually means that you may never need to manipulate ReplicaSet objects: | +| Use a Deployment instead, and define your application in the spec section. | use a Deployment instead, and define your application in the spec section. | +| Issue the following command: | Issue the following command: | +| kubectl get pods | kubectl get pods | + + +## UI Elements + + +When referring to specific product user interface components, use the following approved terms. + +| Component | Spectro Cloud Term | Example | +|-----------------|--------------------|------------------------------------------------------------------------| +| Navbar | Main Menu | Navigate to the left Main Menu and click on Tenant Settings. | +| User Dropdown | User Menu | You can logout by navigating to the top right User Menu. | +| Nested Navbar | Menu | Navigate to the Main Menu and click on Tenant Settings. Next, on the Tenant Settings Menu, click on API Keys. | +| Three Dots | Three Dots | Click on the three-dot Menu | +| Drop Down Menu | Drop Down Menu | Click on the drop-down Menu | + + +For UI elements that contain a symbol or emoji, only include the text. If the button only has a symbol, then use the symbol in the documentation. + +Example: +Add Cluster Profile, write it as Add Cluster Profile. + +Example: + button. Write it as + and refer to the UI element context. “Click on the Addon Layers row + button. + + +## Commands and Parameters + +Always use the long form of a command, as it helps the reader better understand the command's actions. + +| Good ✅ | Bad ❌ | +|-------------------------------------------------|---------------------------------------------| +| kubectl get pods --namespace service_banking | kubectl get pods -n service_banking | + +### Command Output + +Show the command output to help the reader follow along and validate they are receiving the expected output. + + +``` +$ kind create cluster +Creating cluster "kind" ... +✓ Ensuring node image (kindest/node:v1.25.3) 🖼 +✓ Preparing nodes 📦 +✓ Writing configuration 📜 +✓ Starting control-plane 🕹️ + +✓ Installing CNI 🔌 +✓ Installing StorageClass 💾 +Set kubectl context to "kind-kind" +You can now use your cluster with: +kubectl cluster-info --context kind-kind +Have a nice day! 👋 + +``` + +You can break up the command and output using two code blocks. Breaking up the command from the output improves the reader experience because now the reader can copy the command without including the output. + +``` +$ kubectl get pods --namespace nginx +NAME READY STATUS RESTARTS AGE +nginx-deployment-5f76d98944-6gwpj 1/1 Running 0 10m +nginx-deployment-5f76d98944-gw8ns 1/1 Running 0 10m +nginx-deployment-5f76d98944-t5km5 1/1 Running 0 10m. + +``` + +### Parameters + + +Document parameters to provide users with comprehensive and accessible information to effectively configure and utilize the system or software. Ensure clarity, consistency, and ease of understanding in your parameter documentation. + +- Provide a descriptive name and brief description. + +- Specify the data type and default value (if applicable). + +- Outline allowed values or rangesfor the parameter. + +- Indicate if the parameter is required or optional. + +- Explain any dependencies or interactions with other parameters. + +- Offer usage examples for practical understanding. + +- Use a table format for multiple parameters. Include columns for the parameter name, description, type, default values, and requirement status. + +- Maintain formatting consistency and clarity throughout the documentation. + +Using the correct path, specify the main object, sub-object, properties, and any standalone parameter. + +Here is an example. + +| Parameter Name | Description | Data Type | Default Value | Allowed Values | Required/Optional | Dependencies/Interactions | Usage Example | +|-------------------|-------------------------------------------------------------|-----------|---------------|-----------------|-------------------|----------------------------|----------------------------------------------| +| internal | Specifies the MongoDB deployment type | Boolean | n/a | n/a | Required | n/a | `internal: true` | +| databaseUrl | URL for MongoDB | String | n/a | n/a | Required | n/a | `databaseUrl: mongodb://localhost:27017` | +| databasePassword | The password for MongoDB | String | "" | n/a | Optional | Depends on `internal` | `databasePassword: mysecretpassword` | +| replicas | Number of MongoDB replicas to start | Integer | 3 | 1 to 10 | Required | n/a | `replicas: 5` | + + +The above table includes the following details for each parameter: + +**Parameter Name**: Descriptive name for the parameter. + +**Description**: Brief explanation of the parameter's purpose. + +**Data Type**: The type of data expected for the parameter. + +**Default Value**: The default value assigned to the parameter, if applicable. + +**Allowed Values**: The valid options or ranges for the parameter. + +**Required/Optional**: Indicates whether the parameter is required or optional. + +**Dependencies/Interactions**: Any dependencies or interactions with other parameters. + +**Usage Example**: Practical example showcasing how the parameter is used. \ No newline at end of file diff --git a/styleguide/spectro-cloud-word-list.md b/styleguide/spectro-cloud-word-list.md new file mode 100644 index 0000000000..2855eff850 --- /dev/null +++ b/styleguide/spectro-cloud-word-list.md @@ -0,0 +1,37 @@ +# Spectro Cloud Word List + +The Spectro Cloud Word List is a reference to ensure we speak the same language. It provides unified language and terminology across our communication materials, including documentation, marketing content, and internal communications. + +We believe in clear and consistent communication and use this reference to reflect a unified voice and consistent messaging. Review this list to avoid confusion, misinterpretation, or inconsistency when discussing key concepts and ideas. + +- <feature> menu - When referring to a feature’s sub-menu, such as tenant settings, refer to the menu by the features name, ex: tenant settings menu. + +- bare metal - two words. + +- cluster group - two words. + +- data center - two words. + +- Day-2 - always a proper noun. + +- drop-down menu - hyphen. + +- load balancer - two words when used as a noun. + +- log in - use as a verb. + +- login - (noun, adj). + +- Main menu - the main navigation pane of the product. + +- Palette Virtual Cluster - may be referenced as “virtual cluster” after initially defined in its full name. + +- prerequisite(s) - no hyphen. + +- unprotected - no hyphen. + +- User menu - the user menu that contains individual user actions such as logout and more. + +- on-prem - two words using hyphen. + +- out-of-the-box - include _the_. diff --git a/styleguide/troubleshooting-layout.md b/styleguide/troubleshooting-layout.md new file mode 100644 index 0000000000..dcddd93c34 --- /dev/null +++ b/styleguide/troubleshooting-layout.md @@ -0,0 +1,33 @@ +# Troubleshooting Layout + +All Spectro Cloud troubleshooting guides are expected to have the same look and feel. The troubleshooting text and voice must adhere to the Spectro Cloud [style guide](https://github.com/rahulhazra97/Documentation-Guide/wiki/Spectro-Cloud-Style-Guide) for a universal look and feel. The guide must also feel familiar to the reader. Therefore, all troubleshooting guides must follow the layout standard described on this page. + +# Table of Contents + + [Markdown Layout](#markdown-layout) + + [Section Breakdown](#section-breakdown) + + +## Markdown Layout + +The following is a high-level overview of the markdown structure that all troubleshooting guides must contain. Take note of the markdown heading sizes. +``` +# Scenario - + + + +## Debugging Steps + + +``` + +## Section Breakdown + +| Section | Description | +|----------------|-------------| +| Scenario (Title) | The name assigned to the troubleshooting scenario. Aim for a brief title, ideally less than five words. | +| Intro Paragraph | The introduction sets the context for the troubleshooting guide and explains the issue. | +| Debugging Steps | The step-by-step flow of how to address the issue or how to identify the problem. | + +For questions or concerns, please ask in the Slack channel `education`. \ No newline at end of file diff --git a/styleguide/tutorial-layout.md b/styleguide/tutorial-layout.md new file mode 100644 index 0000000000..d0c264b94f --- /dev/null +++ b/styleguide/tutorial-layout.md @@ -0,0 +1,77 @@ +# Tutorial Layout + +To create an impactful tutorial guide, you must create a tutorial plan and obtain stakeholder approval for alignment. Adhere to the [Tutorial Plan](#tutorial-plan) section, and the [Tutorial Layout](#tutorial-layout) section to deliver accurate, user-friendly, and impactful tutorials consistently. + +## [Tutorial Plan Template](https://github.com/rahulhazra97/Documentation-Guide/wiki/Tutorial-Plan-Template) + +All tutorials require a tutorial plan document with stakeholder signoff before authoring. Writing the plan out prevents incorrect deliverables and reduces the chance of time spent inefficiently. The tutorial plan process will help you create a much higher-quality tutorial. + +Find the tutorial plan template from the [Tutorial Plan Template](https://github.com/rahulhazra97/Documentation-Guide/wiki/Tutorial-Plan-Template) page. + +Reach out to us at spectro-docs@spectrocloud.com, to propose a tutorial plan template. + +# Table of Contents + + [Tutorial Layout](#tutorial-layout) + + [Markdown Layout](#markdown_layout) + + [Section Breakdown](#section-breakdown) + + + +## Tutorial Layout + +All Spectro Cloud tutorials are expected to have the same look and feel. The tutorial text and voice must adhere to the Spectro Cloud [style guide](https://github.com/rahulhazra97/Documentation-Guide/wiki/Spectro-Cloud-Style-Guide) for a universal look and feel. The tutorial layout must also feel familiar to the reader, therefore, all tutorials must follow the layout standard described on this page. + +## Markdown Layout + +The following is a high-level overview of the markdown structure that all tutorials should contain. Make a note of the markdown heading sizes. + +``` +# Title + +# Prerequisites + + +# Clone GitHub Repository + + +# [Concept 1] + + +## [Sub-concept 1] + + +## [Sub-concept 2] + + +# [Concept 2] + + +## [Sub-concept 1] + + +## [Sub-concept 2] + + +# Cleanup + + +# Wrap-Up +``` + +## Section Breakdown + +| Section | Description | +|---------------------------|-------------| +| Title | The name assigned to the tutorial. Aim for a title that is no longer than five words. | +| Intro Body | The introduction sets the context for the tutorial and explains the challenge. The introduction must also provide the user with an explanation of what they will learn in this tutorial. | +| Prerequisites | List the required software or hardware the practitioner must have installed and available to complete the tutorial. | +| Clone GitHub Repository | Most tutorials are expected to have a public GitHub repository containing a versioned copy of the tutorial code, if applicable. In this section, the user should be walked through the following commands: | +| [Concept] | The title of one of the main concepts of the tutorial. This could be one of several main concepts. Example - “Configure the Environment” | +| [Sub-Concept] | The title of a child concept stems from the parent concept. Example - “Create Secondary Cluster” OR “App Model Overview” | +| Cleanup | All tutorials should ideally be deployed through infrastructure as code (IaC) if applicable. All resources deployed by the tutorial should be removed. It is our responsibility to help and provide guidance to the user on how to remove all resources. Sometimes this section is brief with a simple command `terraform destroy -auto-approve`. | +| Wrap-Up | This section summarizes the key learning concepts and the actions the practitioner conducted. Additionally, this section should link to or suggest the next set of topics that the practitioner can dive into. | + +For any further information contact : `spectro-docs@spectrocloud.com diff --git a/styleguide/tutorial-plan-template.md b/styleguide/tutorial-plan-template.md new file mode 100644 index 0000000000..0c49f9e528 --- /dev/null +++ b/styleguide/tutorial-plan-template.md @@ -0,0 +1,82 @@ +This page outlines the [Tutorial Plan](#tutorial-plan) template. Use the following template as your reference to create your Tutorial Plan. + +For your next steps, refer to the [Tutorial Layout](https://github.com/rahulhazra97/Documentation-Guide/wiki/Tutorial-Layout#tutorial-layout) page. +

+ +

Tutorial Plan

+ +Author: + +Date: + + +## Learning Objective +_What is the learning outcome of this tutorial? What is the practitioner intended to learn?_ +

+ + +## Learning Sub-objectives +_What learning sub-objectives are emphasized in this tutorial?_ +

+ + +## Tutorial Title +_What is the proposed tutorial title? Titles that answer a question improve SEO score._ +

+ + +## Tutorial Description +_What is the description of the tutorial? The description is used by search engines so it plays a critical role in improving SEO scores_ +

+ + +## Learning Difficulty +_What is the learning difficulty level of this tutorial?_ +

+ + +## Target Audience +_Who is the target audience?_ +

+ + +## Learning Scenario +__What is the learning scenario the practitioner will be exposed to? Will there be a hands-on exercise?__ +

+ + +## Tutorial Requirements +What requirements will the tutorial and the learning exercises have? +

+ + +## Tutorial Assets +_What assets or resources will the author create to support this tutorial? This includes custom code, repository, images and diagrams._ +

+ + +## Cost Management +_What expenses will the practitioner incur because of this tutorial?_ +

+ + +## Tutorial Outline +_What is the outline of the text?_ +

+ + +## Research Resources +_List any documentation resources that will be used to create this tutorial._ +

+ +## Abandoned Ideas +
+ +# Stakeholder Signoff + +Name | Area | Status  ✅ \| ❌ +-- | -- | -- +  | [Engineering] |   +  | [Product] |   +  | [Education] |   + diff --git a/vale/styles/Vocab/Internal/accept.txt b/vale/styles/Vocab/Internal/accept.txt index e840fecb66..6b9c2a7788 100644 --- a/vale/styles/Vocab/Internal/accept.txt +++ b/vale/styles/Vocab/Internal/accept.txt @@ -21,6 +21,7 @@ modify VNet Kubelet We +we vSphere kubeadm upsize