Best practices

These practices cover key aspects of content creation, organization, importing, and publication, helping maintain long-term scalability and editorial control.

Document Organization #

Titles:

• Use descriptive, searchable titles
• Include key terms users might search
• Keep concise but informative

Categories:

• Assign relevant categories consistently
• Use categories for logical grouping
• Consider end-user query patterns

URLs:

• Keep URLs updated for reference
• Document source for imported content
• Use for content refresh workflows

Content Status Management #

When to Use Draft Status #

• Making major content overhauls that require time
• Temporarily removing outdated information from production
• Working on content that’s not yet ready for users
• Collaborating with others before final review
• Preparing scheduled documents that need extensive editing

When to Use Ready Status #

• Content is finalized and reviewed
• Ready for the next publication cycle
• No activation date scheduling needed
• Immediate publication desired upon next publish action

Understanding Scheduled Status #

The SCHEDULED status is automatically assigned by the system when:

• You save a document as “Ready” (or it’s already Ready)
• AND you set a future activation date

Scheduled documents:

• Are NOT included in the publish process
• Become active automatically on their activation date at 00:00 UTC
• Don’t require manual intervention to activate

Scheduling and Date Management #

Planning Activation Dates #

Before First Publication:

• Plan activation dates carefully - they cannot be changed after the document is published
• Consider timezone differences (all dates are in UTC)
• Coordinate with marketing or product launch dates
• Test content in DRAFT status before setting dates

Use Cases for Activation Dates:

1. Seasonal Content: Holiday campaigns, seasonal collections
2. Product Launches: New product information scheduled for release date
3. Events: Conference schedules, webinar information
4. Time-Sensitive Promotions: Black Friday, flash sales

Managing Deactivation Dates #

Unlike activation dates, deactivation dates can always be edited, even for published documents:

• Extend content availability by pushing the date forward
• Shorten availability by moving the date closer
• Remove deactivation entirely to make content permanent
• Add deactivation to existing published documents

Automatic Deactivation:

• Documents reaching their deactivation date automatically become UNPUBLISHED
• Unpublished documents are no longer used to answer user questions
• No manual intervention required

Use Cases for Deactivation Dates:

1. Limited-Time Offers: Automatically expire promotional content
2. Temporary Policies: COVID-19 policies, temporary store hours
3. Event Content: Conference info that becomes irrelevant after the event
4. Seasonal Information: Summer hours, holiday schedules

Date Management Workflow #

Creating New Document:

1. Draft → Set dates → Save as Ready
2. System checks activation date
3. Future date? → SCHEDULED
4. No date? → READY
5. Publish all changes

Editing Published Document:

1. Open document
2. Can change: Content, categories, deactivation date
3. Cannot change: Activation date (locked)
4. Save as Ready → Triggers unpublished changes
5. Publish all changes

Import Workflows #

Single URL Import:

• Use for individual pages
• Immediate feedback and redirect
• Good for quick additions
• Available in Add Document

Bulk Import:

• Use for multiple related documents
• Efficient for documentation migration
• Can organize by categories
• See Import Documents section

Before Importing:

• Verify URLs are accessible
• Check content quality at source
• Ensure proper formatting at source
• Plan category assignments

After Importing:

• Review imported content
• Adjust categories if needed
• Set activation/deactivation dates if applicable
• Verify accuracy before publishing

Publication Strategy #

Pre-Publication Checklist:

• Review all documents marked as READY or SCHEDULED
• Check for duplicate content
• Verify category assignments
• Confirm scheduled dates are correct
• Test sample queries if possible

Avoid During Publication:

• Don’t navigate away during active publication
• Don’t close browser tab
• Don’t start another publication
• Wait for completion notification

Post-Publication:

• Verify content appears correctly
• Test assistant responses
• Monitor for any issues
• Check that scheduled documents show correct status

Categorization Best Practices #

1. Be Specific: Choose categories that precisely match your document’s content
2. Use Multiple When Appropriate: If content spans topics, assign all relevant categories
3. Avoid Over-categorization: Don’t assign categories that are only tangentially related
4. Reserve Uncategorized: Use uncategorized only for truly general content that applies to all topics
5. Test and Refine: Monitor which documents are retrieved for user questions and adjust categories accordingly

See Categories section for more details.

Handling Manual Changes #

When editing documents that were previously imported:

1. Check the “Changes?” indicator in the Document List
2. Document your changes before re-importing (they will be overwritten)
3. Decide priority: Manual edits vs. source content
4. Consider editing at source: If possible, update the source URL instead
5. Re-import carefully: Use Reset button in editor to review before committing

Content Calendar Planning #

Advanced Scheduling Strategy:

1. Plan Quarterly: Create documents for upcoming quarters in advance
2. Batch Create: Create multiple DRAFT documents with different activation dates
3. Stagger Dates: Spread activations to maintain fresh content flow
4. Set Reminders: Note when scheduled content will activate
5. Review Pipeline: Regularly check upcoming scheduled documents

Example Content Calendar:

• Week 1: Holiday collection SCHEDULED for Dec 1
• Week 2: Black Friday content SCHEDULED for Nov 24
• Week 3: Gift guide SCHEDULED for Nov 15
• Week 4: New year content SCHEDULED for Jan 1

Common Pitfalls to Avoid #

1. Don’t publish untested scheduled documents - Review content in DRAFT first
2. Don’t forget timezone differences - All dates use UTC
3. Don’t accumulate too many READY documents - Publish regularly
4. Don’t ignore the unpublished changes warning - Address it promptly
5. Don’t set activation dates casually - They cannot be changed after publication
6. Don’t forget to set deactivation dates - Prevent outdated content from staying active
7. Don’t close browser during publication - Wait for completion
8. Don’t re-import without checking manual changes - They will be overwritten

Quality Assurance Checklist #

Before marking a document as Ready:

• Title is descriptive and searchable
• Content is accurate and complete
• Categories are appropriately assigned
• URL is documented (if imported)
• Activation date is correct (if scheduled)
• Deactivation date is set (if time-sensitive)
• “Only for logged users” is configured correctly
• Content is formatted properly
• Links and references are working
• Spelling and grammar are checked