templates

Author: ShashiSubramanya

modules/_templates/best-practices.adoc

@@ -1,13 +1,15 @@
 = <Title: "Best Practices for <noun phrase>">
 :toc: true
 :toclevels: 1
+// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages.
 
-:page-pageid:
+:page-title: <Title text for the page>
+:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "spotter-embed-best-practices">
 :keywords: <comma-separated terms. For example,  "configure auth", "SSO", "SAML">
 :page-type: best-practices
-:page-role:
+:page-role: <Optional>
 :product-version: <version>
-:jira-ref: <DOC-XXXX>
+:jira-ref: <SCAL-XXXXXX>
 // last-reviewed: <Optional>
 
 // 1-2 sentences: what this page covers, who it is for, and what
@@ -53,7 +55,7 @@
 
 == What to avoid
 
-// Optional but high value. Describe common mistakes or patterns.
+// Optional but adds value. Describe common mistakes or patterns.
 // Use WARNING admonitions for practices that risk data loss or security issues.
 
 //WARNING: <Describe a practice that risks data loss, security exposure,or system instability. State the consequence clearly.>

modules/_templates/concept.adoc

@@ -1,20 +1,16 @@
 = <Title: Noun phrase describing the concept>
 :toc: true
 :toclevels: 1
+// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages.
 
-:page-title: <Title — must match the = Title above>
+:page-title: <Title text for the page>
 :page-description: <One sentence: what this page covers and why it matters to the reader.>
-:page-pageid: <Add a unique ID for this page, for example, "embed-sdk-concepts". Required for developer documentation.>
+:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "spotter-embed-overview">
 :keywords: <comma-separated terms for search indexing, for example, "authentication, SSO, SAML, login">
-:page-type: concept
-:page-role:
+:page-role: <Optional>
 :product-version: <version>
-:jira-ref: <DOC-XXXX>
-
-// author:
-// last-reviewed:
-
-// REQUIRED: 1-2 sentence lead — what this concept is and why it matters to developers or administrators.
+:jira-ref: <SCAL-XXXXXX>
+// last-reviewed: <Optional>
 
 ////
 TEMPLATE GUIDE
@@ -42,21 +38,29 @@ Style elements you can use:
   Inline badge : [beta betaBackground]^Beta^
   Version badge: [.version-badge.new]#New#  [.version-badge.deprecated]#Deprecated#
                  [.version-badge.breaking]#Breaking#  [.version-badge.fixed]#Fixed#
+==============
 ////
 
+
+// REQUIRED: a lead sentence for the article with 1-2 sentences. For example, explain what the feature is and why it matters to users.
+
+== Overview
+
+<Intro text>
+
 == How <concept> works
 
 // REQUIRED.
-// Explain the concept clearly. Avoid procedure steps — link to procedure pages instead.
+// Explain the concept clearly. Avoid procedure steps. Link to procedure pages instead.
 // Use plain language; define acronyms on first use.
 //
 // Add a diagram or screenshot if spatial relationships or architecture matter:
-//   image::./images/<diagram-filename>.png[Alt text describing the diagram]
-//
-// Example:
-//   image::./images/embed-architecture.png[ThoughtSpot embedded architecture overview showing the SDK, REST API, and host application layers]
+// Use the following format for images:
+// image::./images/<diagram-filename>.png[Alt text describing the diagram]
+// For example, image::./images/mcp-architecture.png[ThoughtSpot MCP Server architecture]
 //
 // Use admonitions to highlight key information:
+
 // [NOTE]
 // ====
 // Text for a general note or clarification.
@@ -93,6 +97,8 @@ Description of what it does.
 
 // RECOMMENDED.
 // List known limitations, version-specific behavior, or edge cases the reader should know.
+* <Known limitation or constraint.>
+
 // Use admonitions for critical constraints:
 //
 // [IMPORTANT]
@@ -110,12 +116,9 @@ Description of what it does.
 // Enabling this setting affects all users in the org. Confirm with your administrator before proceeding.
 // ====
 
-* <Known limitation or constraint.>
-
-== Related information
+== Additional resources
 
-// REQUIRED.
-// Link to related concept, procedure, and reference pages.
-// "Related information" is the standard heading — do not use "Additional resources" or "See also".
+// REQUIRED. Include links to related concepts, procedures, and reference pages.
 
-* xref:<module>/page.adoc[Link text]
+//* xref:page.adoc[Link text].
+//* link:<URL>[Link text, window=_blank]

modules/_templates/faqs.adoc

@@ -1,30 +1,30 @@
 = <Title: Noun phrase, for example, "Frequently Asked Questions: Authentication">
 :toc: true
 :toclevels: 1
-:page-pageid:
+
+
+:page-title: <Title text for the page>
+:page-description: <One sentence: what this page covers and why it matters to the reader.>
+:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "embed-faqs">
+:keywords: <comma-separated terms for search indexing, for example, "authentication, SSO, SAML, login">
 :page-type: faq
-:page-role:
+:page-role: <Optional>
 :product-version: <version>
-:jira-ref: <DOC-XXXX>
-// author:
-// last-reviewed:
+:jira-ref: <SCAL-XXXXXX>
+// last-reviewed: <Optional>
 
 // 1-2 sentences: what topic area these FAQs cover and who they are for.
 // Note: write each question as users would ask it — this improves
 // both findability and GEO citation rates.
 
-== General
+== <Information category. For example, Embed authentication>
 
 === <Question written as a user would ask it, for example, "What authentication methods are supported?">
 
 // Answer directly in the first sentence. Provide detail after.
 // If the answer requires steps, use a numbered list.
 // If the answer links to a full page, link to it and summarize here.
 
-// TODO: verify answer with engineering
-
----
-
 === <Question>
 
 // Answer.
@@ -35,8 +35,6 @@
 
 // Answer.
 
----
-
 === <Question>
 
 // Answer.
@@ -47,8 +45,6 @@
 
 // Answer.
 
----
-
 === <Question>
 
 // Answer.
@@ -61,4 +57,7 @@
 
 == Related information
 
-* xref:<component>:<module>/page.adoc[Link text]
+// Optional. Include links to related concepts, procedures, and reference pages.
+
+//* xref:page.adoc[Link text].
+//* link:<URL>[Link text, window=_blank]

modules/_templates/procedure.adoc

@@ -1,16 +1,16 @@
 = <Title: Verb + Object, for example, "Configure Single Sign-On">
 :toc: true
 :toclevels: 1
+// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages.
 
-:page-title: <Title — must match the = Title above>
+:page-title: <Title text for the page>
 :page-description: <One sentence: what this procedure does and who it is for.>
-:page-pageid: <Add a unique ID for this page, for example, "embed-sdk-concepts". Required for developer documentation.>
+:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page, for example, "embed-sdk-concepts".>
 :page-type: procedure
 :keywords: <comma-separated terms for search indexing, for example, "configure, SSO, SAML, setup">
 :page-role:
 :product-version: <version>
-:jira-ref: <DOC-XXXX>
-// author:
+:jira-ref: <SCAL-XXXXXX>
 // last-reviewed:
 
 ////
@@ -44,28 +44,28 @@ Style elements you can use:
   Inline badge : [beta betaBackground]^Beta^
   Version badge: [.version-badge.new]#New#  [.version-badge.deprecated]#Deprecated#
                  [.version-badge.breaking]#Breaking#
+
+==============
 ////
 
 == Overview
 
 // REQUIRED: 1-2 sentences — what this procedure accomplishes and who it is for.
-// Mention the product area and the role of the reader (developer, administrator, etc.).
-// TODO: verify scope with engineering
-//
-// OPTIONAL: Add a workflow diagram or screenshot of the starting UI state if it helps
-// the reader orient themselves before starting:
-//   image::./images/<workflow-diagram>.png[Workflow overview diagram]
+// Mention the product area and the intended audience (developer, administrator, etc.).
+
+// OPTIONAL: Add a workflow diagram or screenshot of the starting state if required.
+
 
 == Before you begin
 
 // REQUIRED if there are prerequisites. Use "You must" or "You need" for each item.
 // Remove this section only if there are genuinely no prerequisites.
 
-* You must have <role or permission, for example, "Developer or Administrator privilege">.
+* You must have <role or group privilege> to <perform the intended action>.
 * You need access to <system or resource, for example, "a ThoughtSpot Cloud instance with the Embed feature enabled">.
-* <Any additional prerequisite.>
+* <Any additional prerequisite>.
 
-== Procedure
+== <Procedure. Use gerund or action verbs. For example, Configuring variables>
 
 // REQUIRED. Use numbered steps. Each step must describe exactly one action.
 // Include the exact command, UI label, menu path, or code for each step.
@@ -75,33 +75,15 @@ Style elements you can use:
 +
 // OPTIONAL: Screenshot showing the UI state after this step:
 // image::./images/<step1-screenshot>.png[Description of what to see after step 1]
+// For SDK procedures, a code sample is REQUIRED. Use the following format for code samples:
 
-. Step two. For SDK procedures, provide a complete, runnable code sample — REQUIRED.
-+
 [source,JavaScript]
 ----
-import { LiveboardEmbed, AuthType, init } from '@thoughtspot/visual-embed-sdk';
-
-init({
-  thoughtSpotHost: 'https://<your-instance>.thoughtspot.cloud',
-  authType: AuthType.TrustedAuthToken,
-  username: '<username>',
-  getAuthToken: () => getTokenFromYourServer(),
-});
-
-const embed = new LiveboardEmbed('#embed-container', {
-  liveboardId: '<liveboard-GUID>',
-});
-embed.render();
+<code sample>
 ----
-+
-[NOTE]
-====
-Replace `<your-instance>` with your ThoughtSpot Cloud hostname and `<liveboard-GUID>` with the ID of the Liveboard you want to embed.
-====
 
-. Step three. For REST API procedures, provide a cURL request — REQUIRED.
-+
+// For REST API procedures, document the required parameters and provide request and response example.
+
 [source,cURL]
 ----
 curl -X POST \
@@ -112,7 +94,7 @@ curl -X POST \
     "param": "value"
   }'
 ----
-+
+
 // OPTIONAL: Show the expected JSON response inline:
 // [source,JSON]
 // ----
@@ -130,22 +112,18 @@ curl -X POST \
 == Result
 
 // REQUIRED. Describe what the user should see or be able to do after completing the procedure.
-// Be specific — name the UI element, API response, or behavior that confirms success.
-//
+// Be specific. Specify the name the UI element, API response, or behavior that confirms success.
 // OPTIONAL: Screenshot of the expected result:
-// image::./images/<result-screenshot>.png[Expected result after completing the procedure]
 
 == Next steps
 
 // OPTIONAL. Link to the next logical task or a related procedure.
+// * xref:next-procedure.adoc[Next task name]
 
-* xref:<module>/next-procedure.adoc[Next task name]
 
-== Related information
+== Additional resources
 
-// REQUIRED.
-// Link to related concept and reference pages.
-// "Related information" is the standard heading — do not use "Additional resources" or "See also".
+// REQUIRED. Include links to related concepts, procedures, and reference pages.
 
-* xref:<module>/concept-page.adoc[Related concept]
-* xref:<module>/reference-page.adoc[API reference]
+//* xref:page.adoc[Link text].
+//* link:<URL>[Link text, window=_blank]