Spec Stages
Define the stages your specs move through, show each article's stage as a badge to your team and your clients, and keep some stages for publishers to set.
On this page
What stages are for#
A spec rarely goes straight from a first draft to finished. It is written, reviewed, agreed with the client, handed to development. Stages name those steps, so anyone looking at an article can tell where it has got to.
You define the stages once for your workspace, in order. Each article can then be in one stage, or none. The stage shows as a coloured badge on the article, in the Manage articles list, and in the customer Help center.
A stage is a label on the article, not a change to its content. Setting one never changes what the article says, never publishes or unpublishes it, and adds nothing to its history.
Nothing changes until you add a stage
A workspace starts with no stages. Until someone adds the first one, the stage picker, the Stage column and the stage filter do not appear anywhere.
Setting up your stages#
Stages are workspace settings. Open Configure Settings and, under Knowledge Base, choose Stages. The page is shown to holders of Manage Knowledge Base Settings; the default Admin role has it. See Who can set up stages below.
On the Stages page:
- Type a name in the box at the bottom (the placeholder suggests e.g. Ready for development) and click Add stage. The new stage goes to the end of the list.
- Click a stage's colour dot to choose its badge colour.
- Use the up and down arrows to put the stages in the order a spec moves through them.
- Click a stage's name to rename it; the change saves when you leave the box or press Enter.
Every change saves as you make it; there is no Save button.
Clients see stage names
The page says it too: Stage names are shown to clients in the portal. Name each stage for a client to read. "Waiting on legal" is fine; an internal nickname or a note about a colleague is not.
Publishers-only stages#
Switch on Only publishers for a stage that marks a decision, such as Approved or Ready for development. Then only holders of Publish knowledge-base articles can move an article into that stage. Anyone who can edit the article can still move it out again, or clear its stage.
Everyone else sees the stage in the picker marked (publishers only) and cannot choose it.
A work type for each stage#
Each stage also has a work-type picker (No work type until you choose one). It names the kind of work item a spec in that stage turns into, such as Story for Ready for development. Clear it to go back to No work type.
Once a stage has a work type:
- Moving a spec into it offers to create the work. When you move a spec with no work items into the stage, and you can create work items, the editor asks Create its work items? and opens the create dialog.
- Work items created from the spec use that type. In the Create work items dialog the Item type is locked to it (Specs in Ready for development create Story items.), whether the dialog opened from the prompt or from the Work items panel.
Stages without a work type never prompt, and the dialog lets you choose any type. The setting does not apply to items an automation creates: those take the type set in the automation's action. See Specs and work items.
If you archive the work type a stage names, choose another one for the stage: until you do, creating work items from a spec in that stage is refused.
The rules#
| Rule | What happens |
|---|---|
| Names are 1–80 characters | Longer names cannot be typed. |
| Names are unique, ignoring case | A stage named "Review" already exists |
| Up to 25 stages | At 25, Add stage is disabled and the page says A workspace can have up to 25 stages. |
| A stage holding articles cannot be deleted | 3 articles are in this stage. Move them to another stage first. |
To retire a stage, move its articles to another stage (filter each tab of the list by it to find them, see below), then click its bin icon.
Who can set up stages#
Adding, renaming, recolouring, reordering and deleting stages needs Manage Knowledge Base Settings, a Settings permission listed under Knowledge Base on the Permissions page. It requires the Settings module.
When this permission arrived, existing admin roles were given it, and so was any role that already held Edit any member's knowledge-base articles together with access to Settings, so nobody who could manage stages before lost the ability. Edit any member's knowledge-base articles no longer manages stages on its own. To let another role set up stages, grant it Manage Knowledge Base Settings; see Roles & Permissions.
Putting an article in a stage is not a setting and does not need this permission (see the next section).
Putting an article in a stage#
Open the article in the editor. In the Status & lifecycle panel, choose from Stage: one of your stages, or No stage. It saves at once, and the badge appears beside the article's state.
You can stage an article in any state: a draft, a published article or a client spec draft.
To change the stage you need Create knowledge-base articles and edit access to the article, the same access that lets you edit its content: you wrote it, it is shared with you as Can edit, or you hold Edit any member's knowledge-base articles. You do not need permission to edit a published article's words: a stage is a label, not an edit. Without edit access the picker is shown but disabled.
Watchers of the article, or of its category, are told in the app when its stage changes. See Watching articles and categories.
Finding articles by stage#
Once your workspace has stages:
- The Manage articles list gains a Stage column showing each article's badge.
- A stage filter (Any stage) sits beside the article count. Choose a stage to see only its articles on the current tab. It works while browsing and while searching.
Reordering articles by dragging is turned off while the stage filter is on, because the list no longer shows the whole category: Clear the stage filter to reorder articles.
Your team's Library does not show stages. See Searching and browsing.
What your clients see#
In the customer portal a staged article shows its stage as a small coloured badge:
- under its title in the Help center's Browse articles,
- under the title on the article page,
- on the Specs page, which groups the published specs under their stage (specs with none under No stage) and badges each draft, and on the spec page itself.
The portal's Home page counts the company's specs by stage under Specs in progress.
Clients see only the stage's name and colour. They never see whether it is publishers-only or which work type it names, and they cannot change it. See The customer Help center.
Related#
- Client spec drafts: specs your clients write in the portal.
- Approval for published changes: make changes to a published spec wait for a publisher's approval.
- Watching articles and categories: hear when a spec moves stage.
- Specs and work items: link specs to the work built from them, and create that work when a spec reaches a stage.
- Knowledge Base permissions: who can manage and set stages.