Getting your naming conventions right from the start makes everything easier. This guide covers why naming conventions matter in Spekit and how to apply them effectively across Topics, Speks, and Collateral.
📌 Quick-Jump Topics
- Why Are Naming Conventions Important: Searchability, organization, and user experience
- How Should Naming Conventions Be Decided: Making global decisions that work for all teams
- Topics: Naming best practices for organizing batches of content
- Speks: Naming best practices for individual pieces of content
- Collateral: Custom fields, tagging, and categorization
Why Are Naming Conventions Important?
What role do naming conventions play in Spekit?
Effective naming conventions are essential for creating a structured, searchable, and user-friendly content environment. Here's why they matter:
🔎 Searchability
- Think about the keywords users will actually search for and incorporate them into your content names.
- Relevant keywords in content titles significantly improve search accuracy.
🫧 Search Hygiene
- Minimize the number of search results per important keyword to improve accuracy and user experience.
💡 Pro Tip: If there are many Speks aligned to a single term, try using a single Spek as a "menu" with all of the other Speks embedded within it.
🗂️ Organization
- Naming conventions help organize content within Spekit, making it easier to categorize and structure. By following a standardized naming format, users can easily navigate through Topics.
💻 System-Specific Documentation
- Clearly label content that is system-related so users know what tools or platforms it applies to.
🛫 Onboarding Workflows and Resources
- Guide new employees or users to the right resources, answers, and processes at the right time.
How Should Naming Conventions Be Decided?
Who should be involved in setting naming conventions?
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 Center of Excellence (CoE) or steering committee for naming decisions and meet on a regular cadence to keep conventions aligned as your content grows.
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
- Serve as a simple way to organize and govern your content
📂 Topics
What should I keep in mind when naming Topics?
- Use 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 users more context about what the Topic contains — keep the title short and let the description do the explaining.
- Think about how users will mentally group or browse batches of content.
- Clearly label onboarding-specific content so new users can find it easily.
- Ensure Admins and Experts agree on Topic naming for alignment and end-user consistency.
- Make sure each Topic has a clear, recognizable visual icon associated with it.
- Consider how your Topic names will affect search results.
💡 Pro Tip: Too many Topics with the same wording will clutter search results for users — keep Topic names distinct and specific.
🐙 Speks
What should I keep in mind when naming Speks?
- Use clear, descriptive titles.
- Maintain consistency in naming conventions across all Speks.
- Name Speks based on how end-users will actually search for them.
- Reduce Speks with the same title to limit the number of duplicate search results.
💡 Pro Tip: Use linking and embedding to create simple content "menus" that users can choose from — this reduces the need for many similarly named Speks.
⚠️ Note: These naming guidelines do not apply to Field Speks or Embedded Speks.
📑 Collateral
How should I approach naming and organizing collateral in Spekit?
- Use Custom Fields and tagging to categorize and organize collateral.
- As Spekit continues to develop tagging and categorization features, rely on tags for contextual information and use collateral names for direct, descriptive labels that clearly communicate what the content is.