Instructions

Instructions are rich-text documents that provide guidance to contributors working on tasks within a project. They serve as the documentation layer between admins who design pipelines and contributors who execute work.

Each instruction is linked to a specific pipeline and one or more contributor roles. Only contributors with a matching role on that pipeline can view the instruction, giving admins fine-grained control over who sees what.

Who can manage instructions

Creating an instruction

1. In the project sidebar, go to Instructions (under the Manage section).
2. Click New Instruction.
3. Fill in the required fields:

4. Click Create Instruction.

A confirmation toast appears and you are returned to the instructions list.

The content editor

The content editor is a rich text editor that outputs Markdown. It includes a toolbar with:

• Text formatting — Bold, Italic, Strikethrough, Inline code
• Headings — H1, H2, H3
• Lists — Bullet, Numbered, Task list (checkboxes)
• Block elements — Blockquote, Code block, Horizontal rule
• Media — Link, Image (via URL), Table
• History — Undo, Redo

Switch between Edit and Preview tabs to see how the rendered document will look. The preview includes a Table of Contents sidebar generated from your headings.

Editing an instruction

1. Go to Instructions in the project sidebar.
2. Click the pencil icon on the instruction row, or click the instruction title to open it.
3. Modify any field — title, pipeline, contributor roles, or content.
4. Click Save Changes.

Deleting an instruction

1. Go to Instructions in the project sidebar.
2. Click the trash icon on the instruction row.
3. Confirm in the dialog.

Visibility and scoping

Instructions use a two-level scoping model:

1. Pipeline — each instruction belongs to exactly one pipeline.
2. Contributor Roles — each instruction is visible only to contributors whose assigned role matches at least one of the roles selected on the instruction.

A contributor will see an instruction only if both conditions are met: they are assigned to the pipeline's project, and they hold a contributor role that the instruction targets.

Admins (Org Admins and Project Admin Owners) can see all instructions in a project regardless of role assignments.

What contributors see

Contributors access instructions from the Instructions item in their sidebar. The page displays a card grid showing each instruction's title, pipeline, assigned roles, and last-updated date. Clicking a card opens a read-only view of the content with a table of contents sidebar.

If no instructions match a contributor's roles, the page displays: "There are no instructions available for your assigned pipelines and roles."

What admins see

Admins see a table view with columns for Title, Pipeline, Roles, and Last Updated. The table supports:

• Search — filter by instruction title or pipeline name.
• Sorting — click column headers to sort by Title, Pipeline, or Last Updated.
• Pagination — server-side, with a default page size of 10.

Interactions with other features

• Pipeline deletion — if a pipeline is deleted, all instructions linked to it are automatically deleted.
• Project deletion — if a project is deleted, all its instructions are deleted.
• Contributor role deletion — if a contributor role is deleted, the role association is removed from any linked instructions, but the instructions themselves are not deleted. If an instruction loses all its role associations, it becomes invisible to contributors but is still visible to admins, who can re-assign roles to it.
• Pipeline status — when creating or editing an instruction, only active or paused pipelines appear in the dropdown. If a pipeline becomes inactive after an instruction was created, the instruction still exists and remains associated, but the pipeline may not appear in the dropdown for new instructions.

Example

A project has a pipeline called "Content Moderation" with two contributor roles: Moderator and QA Reviewer.

An admin creates two instructions:

1. "Moderation Guidelines" — linked to the Content Moderation pipeline, assigned to the Moderator role. Contains examples of acceptable vs. unacceptable content and escalation criteria.
2. "QA Review Checklist" — linked to the same pipeline, assigned to the QA Reviewer role. Contains the quality rubric and common rejection reasons.

A contributor with the Moderator role sees only "Moderation Guidelines." A contributor with the QA Reviewer role sees only "QA Review Checklist." An admin sees both.

Best practices

• Create a general onboarding instruction targeting all roles to explain the project's goals and contributor expectations.
• Create role-specific instructions for each pipeline that detail the task requirements, quality standards, and annotated examples relevant to that role.
• Include screenshots or examples of good vs. poor submissions where possible.
• Review and update instructions when pipeline forms or processes change — outdated instructions are a common source of contributor errors.
• Use headings consistently so the auto-generated table of contents is useful to contributors reading long documents.