Skip to main content

Symphony Core Tagging Standard

Document Version: 1.2 Last Updated: December 18, 2025 Audience: All Symphony Core Teams

Philosophy​

This tagging system follows the Pareto principle: 20% of tags handle 80% of use cases. Tags are designed for professional Symphony Core business operations, providing consistent metadata for documentation discovery, organization, and workflow automation.

Core Principles:

  • Tags enhance discoverability without creating maintenance burden
  • Use existing tags before creating new ones
  • Keep tag vocabulary minimal and purposeful
  • Hierarchical tags (category/subcategory) provide structure without proliferation
  • Tags complement, not duplicate, directory structure

Table of Contents​

  1. YAML Frontmatter Format
  2. Core Tag Categories
  3. Publishing Targets
  4. Tag Usage Guidelines
  5. When to Create New Tags
  6. Tag Maintenance
  7. Examples
  8. Related Documentation

YAML Frontmatter Format​

All markdown documents should include YAML frontmatter at the top of the file:

---
title: Document Title
version: 1.0
author: Symphony Core Systems Team
last_updated: YYYY-MM-DD
category: Category Name
tags: [tag1, tag2, tag3]
status: draft|active|archived|deprecated
audience: internal-team|client-facing|all-teams
---

Required Fields:

  • title: Human-readable document title
  • tags: Array of relevant tags (2-6 tags recommended)
  • status: Current document status

Recommended Fields:

  • version: Document version (semantic versioning)
  • last_updated: Date in YYYY-MM-DD format
  • category: High-level categorization
  • author: Document owner or team
  • audience: Target audience for the document

Optional Fields:

  • supersedes: Previous version(s) this document replaces
  • related_documents: Links to related documentation
  • review_schedule: Quarterly, annually, etc.
  • confidentiality: public, internal, confidential
  • publish_to: Target platforms for publishing (see Publishing Targets)

Core Tag Categories​

1. Functional Area Tags​

Identify the primary business function or domain:

  • strategy - Business strategy, planning, competitive analysis
  • marketing - Marketing campaigns, content, brand, SEO
  • sales - Sales enablement, pricing, proposals, prospecting
  • operations - Operational procedures, checklists, standards
  • platform - Platform configuration, technical implementation
  • training - Team training, knowledge base, educational content
  • customer-education - Customer-facing educational materials
  • reference - Glossaries, standards, quick references

Usage: Select ONE primary functional area tag per document.

2. Document Type Tags​

Classify the document format and purpose:

  • guide - Step-by-step instructional documents
  • sop - Standard Operating Procedure
  • checklist - Task checklists and verification lists
  • template - Reusable document templates
  • standard - Standards and conventions
  • overview - High-level overview or introduction
  • reference - Quick reference or lookup documentation
  • case-study - Client case studies and success stories
  • glossary - Term definitions and vocabulary

Usage: Select ONE document type tag per document.

3. Platform/Tool Tags​

Identify specific platforms or tools discussed:

  • gohighlevel - GoHighLevel platform
  • extendly - Extendly platform and snapshots
  • wordpress - WordPress CMS
  • clickup - ClickUp project management
  • google-workspace - Google Workspace tools
  • github - GitHub and version control
  • 1password - 1Password password management
  • fireflies - Fireflies.ai meeting transcription

Usage: Include platform tags when document is primarily about a specific tool (not just mentions it).

4. Client Tags​

Identify client-specific documentation:

  • client/[client-name] - Use lowercase-with-hyphens format
  • Examples: client/upscale-legal, client/ct-building-broker

Usage: Apply to client-specific implementation docs, profiles, and deliverables.

5. Topic/Subject Tags​

Specific topics within functional areas:

Strategy Topics:

  • business-planning
  • competitor-analysis
  • financial-planning
  • market-research

Marketing Topics:

  • brand-guidelines
  • content-strategy
  • seo
  • social-media

Sales Topics:

  • pricing-strategy
  • proposals
  • contracts

Operations Topics:

  • client-onboarding
  • quality-control
  • testing
  • workflows

Platform Topics:

  • api-documentation
  • automation
  • integration
  • naming-conventions
  • configuration
  • implementation

Usage: Select 1-3 topic tags that describe the specific subject matter.

6. Status Tags (via status field)​

Track document lifecycle:

  • draft - Work in progress, not ready for use
  • active - Current, approved, in use
  • review - Under review or pending approval
  • archived - Historical reference, superseded
  • deprecated - No longer valid, will be removed

Usage: Set ONE status in the status field (NOT in tags array).

7. Publishing Targets​

Identify where documents should be published beyond this repository:

Field: publish_to (array)

Valid Values:

  • internal-wiki - Publish to team.symphonycore.com (internal team documentation)
  • developer-docs - Publish to dev.symphonycore.com (developer/engineering documentation)
  • customer-kb - Publish to customer-facing knowledge base

Usage:

publish_to: [internal-wiki]                # Internal wiki only
publish_to: [developer-docs]               # Developer docs only
publish_to: [customer-kb]                  # Customer KB only
publish_to: [internal-wiki, developer-docs]  # Both internal platforms

When to Use:

  • Document is polished, reviewed, and ready for broader consumption
  • Content is foundational (standards, architecture, key processes)
  • Document should be discoverable outside this repository

Target Selection Guide:

Content TypeTarget
SOPs, operational processes, platform configinternal-wiki
Repository docs, architecture, sprint specs, API contractsdeveloper-docs
Customer-facing guides, how-to articlescustomer-kb
Standards used by both ops and devs[internal-wiki, developer-docs]

When NOT to Use:

  • Draft or work-in-progress documents
  • Client-specific implementation details
  • Temporary project documentation
  • Documents that reference local file paths or internal-only context

Note: The publish_to field indicates intent. Actual publishing requires separate tooling or manual sync to target platforms.

8. Priority/Importance Tags​

Use sparingly for critical documents:

  • critical - Mission-critical, frequently referenced
  • onboarding-required - Required for new team member onboarding
  • client-facing - Customer-visible documentation

Usage: Only apply when document has special importance or visibility.

Tag Usage Guidelines​

General Tagging Best Practices​

  1. Tag Minimally (2-6 tags)

    • More tags ≠ better organization
    • Focus on tags that improve discoverability
    • Avoid redundancy with directory structure

  2. Use Established Tags First

    • Review existing tags before creating new ones
    • Consistency matters more than perfect granularity
    • Reference this document's tag categories

  3. Hierarchical Tags for Organization

    • Use / for hierarchical relationships
    • Example: client/upscale-legal, platform/gohighlevel
    • Keeps tag vocabulary manageable

  4. Client-Specific Content

    tags: [client/upscale-legal, implementation, gohighlevel, automation]

  5. Platform Configuration

    tags: [platform, configuration, gohighlevel, standard]

  6. Operational Procedures

    tags: [operations, sop, client-onboarding, wordpress]

  7. Team Training Materials

    tags: [training, guide, extendly, onboarding-required]

What NOT to Tag​

  • Don't duplicate directory structure: If document is in 04-operations/sops/, don't add both operations AND sop tags
  • Don't tag obvious metadata: Don't tag with author names, dates, or version numbers
  • Don't create single-use tags: If a tag applies to only one document, it's not useful
  • Don't over-specify: wordpress-plugin-setup should just be wordpress + guide

When to Create New Tags​

Creating new tags requires careful consideration. Use this decision framework:

✅ CREATE a new tag when:​

  1. Serves >5% of repository content

    • Will this tag apply to at least 5-10 documents?
    • Is there a clear category of content this organizes?

  2. Fills a clear gap

    • No existing tag adequately describes this content
    • Tag represents a distinct, recurring topic

  3. Improves discoverability

    • Users would logically search for this term
    • Tag makes content easier to find than directory structure alone

  4. New client or platform added

    • New client: client/[client-name]
    • New platform: [platform-name]

  5. New functional initiative

    • New business area or significant project
    • Will generate multiple related documents

❌ DON'T CREATE a new tag when:​

  1. Existing tag is "close enough"

    • Better to use an established tag than create near-duplicates
    • Example: Don't create wordpress-themes when wordpress exists

  2. Only applies to 1-2 documents

    • Tags are for organization, not ultra-specific classification
    • Use document title and content for specific details

  3. Duplicates directory structure

    • Directory already provides this organization
    • Example: Don't tag /03-sales/pricing-strategy/ docs with both sales AND pricing-strategy

  4. Temporary or project-specific

    • Avoid tags for short-term projects
    • Use project names in titles instead

  5. Too specific or granular

    • email-configuration can just be configuration
    • Let document content provide specificity

New Tag Proposal Process​

Before creating a new tag:

  1. Search existing tags in repository
  2. Check if existing tag + topic combination works
  3. Estimate affected documents (should be 5+)
  4. Document rationale in commit message if creating new tag category
  5. Update this document if creating new tag category (not individual client/platform tags)

Tag Maintenance​

Monthly Review​

  • Review tag usage in recently created/updated documents
  • Ensure consistency with this standard
  • Identify commonly co-occurring tags (may indicate missing category)

Quarterly Assessment​

  • Analyze tag usage across repository
  • Identify underutilized tags (candidates for removal)
  • Identify heavily-tagged topics (may need new tag)
  • Update this document with new approved tags

Annual Cleanup​

  • Remove tags with <1% usage (applied to fewer than 5 documents)
  • Consolidate near-duplicate tags
  • Archive deprecated tags (document in changelog)
  • Maintain Pareto principle: 20% of tags handle 80% of needs

Tag Evolution Metrics​

Monitor these metrics quarterly:

  • Tag coverage: % of documents with appropriate tags
  • Tag cardinality: Average tags per document (target: 2-6)
  • Tag distribution: Top 20% of tags should cover 80% of documents
  • Orphaned tags: Tags applied to only 1-2 documents

Examples​

Example 1: Client Implementation Guide​

---
title: Upscale Legal Implementation Tasks
version: 1.0
author: Symphony Core Systems Team
last_updated: 2025-11-05
category: Implementation
tags: [client/upscale-legal, implementation, extendly, automation, guide]
status: active
audience: internal-team
---

Rationale:

  • client/upscale-legal: Client-specific content
  • implementation: Document type
  • extendly: Primary platform
  • automation: Key technical focus
  • guide: Document format

Example 2: Platform Configuration Standard​

---
title: GoHighLevel Configuration Standard
version: 2.1
author: Symphony Core Systems Team
last_updated: 2025-09-15
category: Standards
tags: [platform, gohighlevel, configuration, standard]
status: active
audience: internal-team
---

Rationale:

  • platform: Functional area
  • gohighlevel: Specific platform
  • configuration: Topic
  • standard: Document type

Example 3: Operational SOP​

---
title: Client Onboarding Checklist
version: 3.0
author: Symphony Core Systems Team
last_updated: 2025-08-04
category: Operations
tags: [operations, sop, client-onboarding, checklist, onboarding-required]
status: active
audience: internal-team
---

Rationale:

  • operations: Functional area
  • sop: Document type
  • client-onboarding: Specific topic
  • checklist: Format
  • onboarding-required: Special importance

Example 4: Marketing Content​

---
title: Brand Voice Guidelines
version: 1.5
author: Symphony Core Marketing
last_updated: 2025-07-20
category: Brand
tags: [marketing, brand-guidelines, content-strategy, reference, client-facing]
status: active
audience: all-teams
---

Rationale:

  • marketing: Functional area
  • brand-guidelines: Specific topic
  • content-strategy: Related topic
  • reference: Document type
  • client-facing: Special visibility

Example 5: Team Training Material​

---
title: Extendly Quick Start Guide
version: 2.0
author: Symphony Core Training Team
last_updated: 2025-10-01
category: Training
tags: [training, extendly, guide, onboarding-required, platform]
status: active
audience: internal-team
---

Rationale:

  • training: Functional area
  • extendly: Platform focus
  • guide: Document type
  • onboarding-required: Critical for new team members
  • platform: Secondary functional area

Example 6: Foundational Document for Wiki Publishing​

---
title: SC Software Repository Inventory
version: 2.4
author: Symphony Core Systems Team
last_updated: 2025-12-18
category: Reference
tags: [reference, platform, github, overview]
status: active
audience: internal-team
publish_to: [internal-wiki]
---

Rationale:

  • publish_to: [internal-wiki]: Foundational reference that should be available on team.symphonycore.com
  • Document is polished, stable, and broadly useful
  • No client-specific or sensitive information

Common Tag Combinations​

Client Work​

tags: [client/[name], implementation, [platform], [topic]]

Platform Documentation​

tags: [platform, [platform-name], [document-type], [topic]]

Operational Procedures​

tags: [operations, [document-type], [topic], [platform]]

Sales & Marketing​

tags: [sales|marketing, [topic], [document-type]]

Standards & References​

tags: [reference, standard, [topic]]

Integration Points​

Documentation Tools​

  • Obsidian: Tag search and filtering via native tag pane
  • GitHub: Searchable via grep/ripgrep for metadata queries
  • Claude Code: AI assistant uses tags for context understanding
  • Future: Automated documentation dashboards and analytics

Automated Workflows​

  • Tag-based document categorization
  • Automated cross-referencing
  • Document lifecycle tracking
  • Compliance and review scheduling

Search & Discovery​

  • Filter documents by functional area
  • Find all client-specific documentation
  • Identify platform-specific guides
  • Locate onboarding-required materials

Changelog​

Version 1.2 (2025-12-18)​

  • Added developer-docs target for dev.symphonycore.com (engineering documentation)
  • Added Target Selection Guide table for choosing appropriate publish target
  • Supports separation of operations docs (team.) from developer docs (dev.)

Version 1.1 (2025-12-18)​

  • Added publish_to field for marking documents for wiki publishing
  • Valid targets: internal-wiki (team.symphonycore.com), customer-kb
  • Added Example 6 demonstrating publish_to usage
  • Updated Table of Contents with Publishing Targets section
  • Applied publish_to: [internal-wiki] to this document

Version 1.0 (2025-01-08)​

  • Initial tagging standard
  • Defined core tag categories
  • Established tag creation criteria
  • Provided usage examples and best practices
  • Documented maintenance procedures

Appendix: Complete Tag Reference​

Functional Areas (Primary Categories)​

  • strategy
  • marketing
  • sales
  • operations
  • platform
  • training
  • customer-education
  • reference

Document Types​

  • guide
  • sop
  • checklist
  • template
  • standard
  • overview
  • reference
  • case-study
  • glossary

Platforms/Tools​

  • gohighlevel
  • extendly
  • wordpress
  • clickup
  • google-workspace
  • github
  • 1password
  • fireflies

Common Topics​

  • automation
  • client-onboarding
  • configuration
  • implementation
  • integration
  • naming-conventions
  • workflows
  • brand-guidelines
  • seo
  • pricing-strategy
  • business-planning

Special Purpose​

  • critical
  • onboarding-required
  • client-facing

Status Values (use status: field, not tags)​

  • draft
  • active
  • review
  • archived
  • deprecated