Create your first workspace and fragment

This journey takes you from an account to a small, working knowledge base. You will create one workspace, publish one durable fragment, and verify that it is retrievable.

Before you begin

You need a Usable account and permission to create a workspace. Decide whether the workspace should be private or discoverable to other signed-in Usable users.

Keep the first scope small. A workspace called “Everything” with no audience or ownership rule becomes difficult to maintain.

1. Define the workspace

Write down:

• the people or systems it serves;
• the knowledge that belongs there;
• what must stay elsewhere;
• whether it is private or public;
• who will maintain it.

A useful scope statement is: “Released integration guidance for customers and support engineers.”

2. Create the workspace

1. Sign in at https://usable.dev.
2. Open Dashboard → Workspaces.
3. Choose the create-workspace action.
4. Enter a short, recognizable name.
5. Add a description that states audience and purpose.
6. Choose visibility deliberately:
   • Private for invite-only material;
   • Public only for content reviewed for broad sharing.
7. If workspace placement is available, choose Cloud unless your organization has an approved Hosted Zone requirement.
8. Save and confirm the workspace opens successfully.

A public workspace is discoverable and subscribable; it is not anonymous write access. Subscribers receive read-style access.

3. Review types and access

New workspaces include usable default fragment types such as Knowledge and Skill. Add a custom type only when authors need a durable distinction the existing types cannot express.

Invite the smallest initial group:

• owners manage settings and access;
• collaborators maintain content;
• viewers read;
• public subscribers read where permitted.

Keep owner access limited.

4. Create the first fragment

Create a fragment named Workspace purpose and contribution guide.

Include:

# Workspace purpose
 
## Audience
Who should use this workspace.
 
## In scope
The durable knowledge that belongs here.
 
## Out of scope
Content that should stay elsewhere.
 
## Contribution rules
How to title, tag, review, and maintain fragments.
 
## Public-safety rule
What must never be added or published.

Then:

1. Select the most precise fragment type.
2. Use a title a teammate would search for.
3. Put durable facts in the body, not only the summary.
4. Add a concise summary.
5. Add a few stable tags for topic, audience, owner, repository, or release.
6. Save and reopen the fragment.

Do not include secrets, tokens, customer-confidential data, or private infrastructure details.

5. Verify retrieval

Search for the exact title in the workspace. Then search using a likely natural-language question such as “How should I contribute to this workspace?”

Verify:

• the correct fragment appears;
• its title, summary, type, and tags are accurate;
• the body answers the question without relying on hidden context;
• the intended users can open it;
• unintended users cannot edit it.

If you use MCP, connect the client, search the workspace, and fetch the full fragment before relying on the result.

6. Add structure only when needed

Create collections after you have a real group of related fragments. Upload files only when they are evidence or source material that should remain as a workspace asset. Configure webhooks or applications after the content model and ownership are clear.

Troubleshooting

I cannot create a workspace

Your account or organization may not allow workspace creation. Confirm the signed-in account and ask an administrator to review your capability.

I cannot edit the fragment

Check your workspace role and the fragment status. Viewers and subscribers are read-only.

Search does not find the fragment

Wait briefly for processing, remove strict filters, search the exact title, and confirm the fragment is active in the intended workspace. Provide explicit summary and tags when deterministic metadata matters.

The workspace should be public

Review every fragment, attachment, member-visible field, and automation target before changing visibility. Public workspaces require ongoing review, not a one-time toggle.

Next steps

• Organize and maintain useful knowledge
• Workspaces
• Memory fragments
• Workspace members and invitations