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 Management

Draft → Ready → Published Workflow:

  1. Create document and save as Draft
  2. Review and finalize content
  3. Mark as Ready when complete
  4. Review all Ready documents
  5. Publish to production

Regular Publishing:

  • Publish changes regularly (don’t accumulate)
  • Review Ready documents before publishing
  • Test published content in production

Manual Changes Tracking:

  • Monitor the “Changes?” column
  • Be aware that imports overwrite manual changes
  • Consider making changes to source content instead

Import Workflows

Single URL Import:

  • Use for individual pages
  • Immediate feedback and redirect
  • Good for quick additions

Bulk Import:

  • Use for multiple related documents
  • Efficient for documentation migration
  • Can organize by categories

Before Importing:

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

After Importing:

  • Review imported content
  • Adjust categories if needed
  • Verify accuracy before publishing

Publication Strategy

Pre-Publication Checklist:

  • Review all documents marked as READY
  • Check for duplicate content
  • Verify category assignments
  • Test sample queries

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

Categorization

  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
← Publication system
Troubleshooting →