Best Practices for Naming Conventions

In this guide, we'll explore the importance of naming conventions in creating a structured and user-friendly environment for content management. From enhancing searchability to optimizing user experience, effective naming conventions play a crucial role in streamlining processes and ensuring clarity across teams. Let's dive in to understand why naming conventions matter and how to implement them effectively.

☝️Why are Naming Conventions important?

• Searchability 🔎
  • What are the keywords users will search for?
  • Incorporate relevant keywords in naming the content to improve search.
• Search hygiene 🫧
  • Minimize the number of search results per important keyword to improve accuracy and user experience

💡 Pro-Tip: If there are many Speks that are aligned to a single term, try using a single Spek as a “menu” with all of the other Speks embedded

• Organization 🗂️
  • Naming conventions help organize content within Spekit, making it easier to categorize and structure content. By following a standardized naming format, users can easily navigate through topics
• System Specific documentation 💻 
  • Label content that is system-related
• Onboarding workflows and resources 🛫
  • Guide new employees or new users when and where they need resources, answers, and process

🧐 How should Naming conventions be decided?

• Naming conventions, similar to consistent design decisions, should be made as a “global decision” for all teams and content creators to participate in

💡 Pro-Tip: Create a CoE (Center of Excellence) or steering committee for decisions and meet on a regular cadence  

• Naming conventions should:
  • Consider the user experience first
  • Maintain brand consistency across all documents
  • Consider how users are going to think about, look for, and navigate content
  • Be simple and easy to understand
  • Be a simple way to organize and govern your content 

📂 Topics 

• Clear titles and categories for process, resources, team-specific content, and system-specific content
• Less is more! Use short meaningful titles instead of long sentences.

💡 Pro-Tip: Use the topic description to give more insights on the topic content to the users 

• How will users think about batches of content
• Onboarding specific content
• Agreement across Admins and Experts as to how Topics are named for alignment and end-user consistency
• Make sure your Topics also have clear visual icons associated with them
• How does naming affect your search results? 

💡 Pro-Tip: Too many Topics with the same wording will clutter up search results for users

🐙 Speks

• Clear Titles
• Consistency in naming conventions
• Search logic according to end-user search behavior
• Reduce Speks with the same title to limit the amount of search results

💡 Pro-Tip: Use linking and embedding Speks to create simple content “menus” that users can choose from 

📝Note: These things do not apply to Field or Embedded Speks

📑 Collateral

• Custom Fields and Tagging
• As we continue to develop our features for tagging and categorization we encourage you to rely on tagging for information, and naming of collateral for direct calls out to what it is