Master this essential documentation concept
A configurable set of rules in a documentation platform that controls which users or groups can view, edit, or administer specific content areas.
A configurable set of rules in a documentation platform that controls which users or groups can view, edit, or administer specific content areas.
When onboarding new team members or rolling out platform changes, many documentation teams default to recording walkthroughs that explain how their permission scheme is structured — who can access what, which groups own which content areas, and how to request elevated access. It makes sense in the moment: a screen recording captures the configuration visually and the presenter can explain the reasoning behind each rule.
The problem surfaces later. When a technical writer needs to verify whether a contractor group has edit rights to a specific content area, scrubbing through a 45-minute onboarding video is not a practical workflow. Permission scheme decisions are often buried mid-recording, undocumented in any searchable format, and impossible to audit without watching the entire clip.
Converting those recordings into structured documentation changes that dynamic entirely. Your team can extract the specific access rules discussed, organize them by role or content area, and make them searchable and linkable — so the next time someone questions why a user group lacks admin rights, the answer is a search query away rather than a timestamp hunt. You can also keep permission scheme documentation versioned alongside your platform configuration, creating a clear audit trail that video alone cannot provide.
If your team is sitting on a library of recorded platform walkthroughs, there is a more practical way to put that knowledge to work.
A SaaS company shares a Confluence space with integration partners, but pre-release feature docs, internal roadmaps, and security advisories are accidentally visible to external partner accounts, creating NDA violations and competitive risk.
A Permission Scheme separates the partner-facing space into two tiers: a 'Partner View' group with read-only access to published API docs, and an 'Internal Only' group restricted to employees, ensuring pre-release pages are invisible to partner logins entirely.
["Audit the existing space and tag all pre-release and internal pages with a dedicated label like 'internal-only'.", "Create a Permission Scheme with two groups: 'External Partners' (View permission only on approved pages) and 'Internal Staff' (View + Edit on all pages).", "Apply page-level restrictions on all 'internal-only' labeled pages to block the 'External Partners' group explicitly.", 'Set up a quarterly permission review task to validate that new pages created by writers are assigned to the correct group before publishing.']
Zero accidental disclosures of pre-release content to partners, with audit logs confirming external accounts can only access 73 approved API reference pages out of 400+ total space pages.
A DevOps team onboards contract technical writers to update user-facing guides, but their documentation platform grants space-wide edit access by default, exposing sensitive production incident runbooks and on-call escalation procedures to contractors.
A Permission Scheme creates a 'Contract Writers' group scoped exclusively to the 'User Guides' and 'Release Notes' sections with Edit permissions, while production runbooks under 'Operations' remain restricted to full-time staff with a separate 'Ops Team' permission group.
["Define two distinct content areas in the platform: 'Customer-Facing Docs' and 'Operations Runbooks', each governed by its own Permission Scheme.", "Create a 'Contract Writers' group assigned View + Edit + Comment rights only within the 'Customer-Facing Docs' scheme.", "Assign all contractors to the 'Contract Writers' group during onboarding, never granting space-admin or global roles.", "Configure the 'Operations Runbooks' scheme to explicitly deny all permissions to the 'Contract Writers' group, overriding any inherited space defaults."]
Contractors can fully contribute to 12 user guide sections without ever seeing operational runbooks, reducing security review overhead by eliminating manual page-by-page restriction setting for each new contractor.
A healthcare technology firm maintains clinical workflow documentation alongside general product guides in the same platform. Compliance auditors find that support staff and marketing employees have read access to pages containing PHI-adjacent process descriptions, violating HIPAA minimum-necessary rules.
A Permission Scheme called 'Clinical Compliance' restricts the clinical documentation space to a 'Clinical Staff' group (verified, HIPAA-trained employees) with View + Edit, while all other platform users are explicitly excluded from the space at the scheme level.
["Work with the compliance team to identify all pages containing PHI-adjacent content and migrate them into a dedicated 'Clinical Workflows' space.", "Create a 'Clinical Compliance' Permission Scheme that grants access exclusively to members of the 'Clinical Staff' Active Directory group, synced via SSO.", "Remove the default 'All logged-in users' view permission from the space and replace it with the explicit 'Clinical Staff' group only.", 'Generate monthly permission audit reports from the platform showing exactly which accounts accessed the clinical space, submitted to the compliance officer.']
Passes HIPAA access control audit with documented proof that only 34 credentialed clinical staff members have any access to clinical documentation, down from 210 employees who previously had implicit access.
An MSP maintains separate documentation for 15 client environments in a single Confluence instance. Client A's engineers can browse to Client B's network architecture docs by guessing page URLs, since all clients share the same global permission defaults.
Each client receives a dedicated space governed by a unique Permission Scheme named after the client (e.g., 'Acme Corp Scheme'), granting View + Edit only to that client's designated contacts and the MSP's internal team, with no cross-client group membership.
["Create one Confluence space per client and apply a uniquely named Permission Scheme to each space that includes only that client's user group and the MSP 'Internal Engineers' group.", "Disable anonymous access and 'All logged-in users' defaults at the global platform level to eliminate permission inheritance loopholes.", "Automate user provisioning so that when a new client contact is added in the CRM, they are automatically added only to their client's permission group via a Jira automation or API script.", "Conduct semi-annual cross-client permission audits by attempting to access each client space with a test account from a different client group, verifying 'Access Denied' responses."]
Complete tenant isolation confirmed across all 15 client spaces, with automated provisioning reducing manual permission setup time from 45 minutes per new client to under 3 minutes.
Assigning permissions directly to individual user accounts creates an unmanageable web of exceptions that breaks when employees change roles or leave the organization. Permission Schemes should reference named groups tied to job functions (e.g., 'Technical Writers', 'Engineering Managers') so that access automatically updates when group membership changes via HR or identity provider sync.
Default platform configurations often grant broad 'All logged-in users' view access, which violates least-privilege principles and exposes sensitive documentation to unintended audiences. Each Permission Scheme should grant only the minimum access level required for a group to perform their specific documentation function, with Edit rights reserved for active contributors.
Permission Schemes without a designated owner become stale, with outdated groups and access levels that no one feels responsible for reviewing. Assigning a named Documentation Administrator or Team Lead as the scheme owner creates accountability and ensures the scheme is reviewed when team structures or content sensitivity changes.
Treating in-progress draft documentation with the same permissions as published content exposes incomplete, inaccurate, or sensitive work-in-progress to audiences who should only see approved material. Maintaining distinct schemes for draft spaces (restricted to writers and reviewers) and published spaces (broader read access) enforces a deliberate content promotion workflow.
Mergers, reorgs, contractor offboarding, and role changes all create stale permission group memberships that accumulate silently over time, gradually expanding access beyond intended boundaries. Scheduling permission audits tied to organizational change events—rather than only on a calendar cadence—catches access drift before it becomes a compliance or security issue.
Join thousands of teams creating outstanding documentation
Start Free Trial