Organize and maintain useful knowledge

A useful Usable workspace is organized for retrieval and maintained as knowledge changes. Structure should help people and AI clients find the authoritative fragment without creating parallel versions of the same fact.

Start with boundaries

Use a workspace for a stable audience, purpose, access boundary, or operational owner. Split content when it has a materially different audience or confidentiality requirement—not merely because it has a different topic.

Document the workspace purpose, content policy, owners, and review expectations in a visible fragment.

Use metadata as one system

Each mechanism has a different job:

• Workspace: audience and access boundary.
• Fragment type: kind of knowledge, such as Knowledge, Recipe, Solution, or Skill.
• Title: the phrase a person would search for.
• Summary: scan-friendly statement of scope and outcome.
• Tags: cross-cutting filters such as topic, repository, version, audience, or status.
• Collection: curated reading set or maintained bundle.
• Status: lifecycle signal where draft, published, or archived is exposed.

Do not compensate for vague titles with dozens of tags. Do not create a type for every team or topic.

Choose a useful fragment scope

A fragment should be independently understandable and focused enough to retrieve.

Split content when:

• sections answer different user questions;
• permissions or release cadence differ;
• one section changes much more often;
• search results should return one part without the rest.

Keep content together when the steps form one outcome and splitting would force readers to reconstruct the procedure.

Write for retrieval

• Put the answer in the body.
• State the context and audience near the start.
• Use descriptive headings.
• Include exact product terms users will search for.
• Add release or verification context when behavior changes by version.
• Explain prerequisites, expected result, and failure modes.
• Link canonical related pages instead of copying them.

AI-generated summaries and tags can help, but explicit metadata is safer for deterministic imports and important documentation.

Prevent duplicates

Before creating a fragment:

1. Search the likely title and synonyms.
2. Check related collections.
3. Fetch candidate fragments in full.
4. Update the canonical fragment when the scope matches.
5. Create a new fragment only for a distinct audience, lifecycle, permission boundary, or question.

If two fragments conflict, identify the owner and authoritative source. Merge durable content, redirect links, then archive the obsolete fragment when historical context matters.

Handle versions and stale knowledge

Prefer one maintained page for current behavior. Add release anchors when behavior is version-specific, but avoid copying a full page per patch release.

A review should ask:

• Is the behavior still released?
• Is the owner still responsible?
• Are links, files, and examples current?
• Does the title still match the content?
• Is another fragment now canonical?
• Is public content still safe?

Archive content that remains useful for history. Delete only when retention, references, and audit needs allow it.

Establish ownership

For important fragments, record an owner through the workspace's naming/tagging convention or content. Define a review trigger such as a release, policy change, incident, or scheduled interval.

A practical maintenance loop:

change detected → find canonical fragment → verify source → update → review safety → publish → test retrieval → clean stale links/files

Maintain collections and files

Collections are reading sets, not substitutes for metadata. Review their membership after publishing, archiving, or renaming fragments.

Files should support a fragment rather than replace its explanation. Use descriptive filenames, remove stale attachments, and keep the fragment useful if a file later disappears.

Public-safety review

Before publishing or moving content into a public workspace, check:

• secrets, tokens, cookies, keys, and credentials;
• customer or personal data;
• private URLs, hostnames, tickets, and topology;
• screenshots and file metadata;
• internal plans presented as shipped behavior;
• broad auto-link rules or webhooks that could disclose content;
• links to private-only sources that public readers cannot use.

If a credential was exposed, remove the content and rotate the credential immediately.

Verify with humans and AI

After a substantial change:

1. Open the rendered fragment.
2. Search by title, synonym, and task-oriented question.
3. Confirm an AI client discovers the fragment.
4. Fetch full content and confirm it answers the question.
5. Check related links and collection placement.
6. Test with the lowest intended role.

Related pages

• Create your first workspace and fragment
• Publish and share knowledge safely
• Search and retrieval
• Tags and summaries
• Collections