Tags and summaries

Summaries and tags describe a fragment from two different angles. A summary explains the fragment in a sentence or short paragraph. Tags attach reusable labels that can be filtered and recognized across many fragments.

Both help people and AI discover useful material, but neither compensates for unclear content. Treat them as accurate signposts for a well-written fragment.

Write a summary for selection

A good summary helps someone decide whether to open the fragment. It should state what the fragment contains and, when useful, the situation it applies to.

For example:

Explains how workspace-scoped fragment keys support stable API lookups, including format rules and duplicate-key handling.

That is more useful than:

Documentation about fragment keys.

The stronger version names the subject and the important boundaries. It gives search and AI retrieval more meaningful context without repeating the entire introduction.

Human-written and generated summaries

Usable can generate summaries in supported creation workflows. Generation is a helpful starting point, especially during imports, but the result should still be reviewed.

Generated text may overstate what the fragment proves, miss an important limitation, or describe the format instead of the substance. Edit it when a concise human explanation would be clearer.

Update the summary when the fragment’s purpose changes. A stale summary can cause readers and agents to select the wrong source even when the body is correct.

Use tags as a shared vocabulary

Tags work best when their meaning is consistent across the workspace. Useful tags often identify:

• a product or domain, such as usable or authentication;
• a technical area, such as api or webhooks;
• an audience or workflow, when that convention is established;
• a repository, release, or other stable scope used by integrations.

Use lowercase, readable names unless your workspace has a different documented convention. Namespace a tag when the prefix adds meaning, such as repo:usable or version:v2.

Avoid tag sprawl

Adding every word related to a fragment does not improve discovery. It creates overlapping spellings and makes filters unreliable.

Before adding a tag, ask:

1. Will other fragments use this label?
2. Would someone intentionally filter or automate by it?
3. Is there already a tag with the same meaning?

A focused set of stable tags is more valuable than a long list of near-synonyms such as auth, authentication, login-auth, and user-authentication.

Tags are not types or collections

A tag describes an attribute. It does not define the fragment’s primary role, and it does not create a curated reading sequence.

Use a fragment type for what the fragment is. Use a collection when a named set of fragments should be treated together. Use tags for labels that cut across those structures.

For example, several Knowledge, Recipe, and Solution fragments can all carry the authentication tag and belong to an “Authentication onboarding” collection.

How they affect retrieval

Structured listing can filter fragments by tags and other metadata. Semantic and agentic search also benefit from descriptive titles, summaries, tags, and body content when ranking likely sources.

Do not add misleading keywords merely to improve search placement. Retrieval is useful only when the selected fragment actually answers the need.

When an AI client searches Usable, it should still fetch the complete fragment before relying on it. A title, summary, or search reason is a discovery aid—not the source itself.

Example: a deployment Recipe

For a fragment titled “Deploy the API to production”:

Summary

Step-by-step production deployment procedure for the API, including prerequisites, rollout verification, and rollback conditions.

Tags

api, deployment, production, operations

The summary explains the value and scope. The tags connect the procedure to broader subjects without duplicating the title word for word.

Good practices

• Make summaries specific enough to support a selection decision.
• Review generated summaries and tags before saving.
• Use a small, shared tag vocabulary.
• Prefer stable domain labels over temporary wording.
• Avoid synonyms and one-off tags unless they serve a real filter.
• Update metadata when the content’s scope changes.
• Never use tags to imply verification or publication unless your workspace has a controlled convention for it.

Related concepts

• Fragment types classify a fragment’s role.
• Collections curate related fragments into named sets.
• Search and retrieval explains how these signals support discovery.