Specs Overview
Specs are the living documents at the centre of Vanillaround. A spec page is where you write down what needs to be built — with enough context, structure, and precision that a developer can act on it without needing to chase down clarification.
What makes a spec different from a wiki or a ticket
Section titled “What makes a spec different from a wiki or a ticket”A wiki (like Confluence) holds documentation. A ticket (like Jira) tracks a unit of work. A spec page in Vanillaround does something specific to neither: it captures the agreement between a client and a delivery team about what should be built, before the work begins.
The key differences:
- Specs are written before development, not after
- Requirement cards embedded in specs go through a formal approval process
- Every change to a spec page is tracked and attributed
- Specs are real-time collaborative — multiple people can edit simultaneously
Spec anatomy
Section titled “Spec anatomy”A typical spec page contains:
- Context — the business problem or opportunity this feature addresses
- Functional requirements — how the feature should behave
- Requirement cards — discrete, approvable items embedded in the prose
- Open questions — unresolved decisions that need input
- Attachments — mockups, diagrams, or reference documents uploaded directly to the page
Types of pages
Section titled “Types of pages”| Type | Description |
|---|---|
| Requirement page | A standard spec page for a feature or user story |
| Global page | A shared reference page visible across the project (e.g. glossary, architecture diagram, design principles) |
Navigation
Section titled “Navigation”All spec pages for a project are listed in the left sidebar, organised as a tree. Pages can be nested — a parent page for a major feature area, with child pages for each sub-feature or flow.
Frequently-accessed pages can be starred as Favourites and accessed quickly from the sidebar without scrolling through the full tree.