Optimizing your permission groups
Structure roles and access so the right people edit the right articles.
You already have user roles sorted. Someone is an Owner, a couple of people are Editors, a contractor is a Writer, and that ladder decides who can publish, manage billing, or invite teammates. Roles answer “what can this person do to the account.” They do not answer the messier question: “which articles should this person actually see and touch?”
That second question is what permission groups are for, and it is where most knowledge bases get tangled. A well-designed set of groups means support sees support content, partners see partner content, and half-finished internal runbooks never surface to a customer. This guide is about designing those groups to fit your real org so access stops being manual gatekeeping. You can set all of this up in your access and team controls.
What is the difference between roles and permission groups?
Roles are account-level. They rank capability from Read-only through Writer, Editor, and Administrator up to Owner, and they govern actions like editing, publishing, and managing users. If you need a refresher on the ladder, the managing users guide covers it in full, so this article will not re-teach it.
Permission groups are about content scope. In HelpDocs you create a group (in Settings, Access, Groups), then assign both people and articles to it. An article or category is visible only to users who belong to a group it is tagged with. The two systems work together: a role says what someone can do, a group says what they can do it to.
How should you design groups around your team?
Start from your org chart, not from individual people. The goal is a small number of groups that map cleanly onto how work is actually divided. Two patterns cover most teams.
Support tiers. If your support desk escalates, mirror that. An L1 group sees customer-facing how-tos and first-response macros. An L2 or L3 group additionally sees deeper troubleshooting runbooks and known-issue logs that would confuse a customer or a new hire. Nobody has to remember which article is safe to share, because the group already decided.
Departments. Marketing, Sales, Product, and Engineering each own different internal docs. A Product group gets roadmap notes and feature specs, Marketing gets style guides and campaign playbooks, and neither wanders into the other’s drafts. HelpDocs lets a person sit in several groups at once, so a product marketer can belong to both without you cloning content.
How do internal and external audiences fit in?
The biggest split is usually internal versus external. Public help articles are visible to everyone by default, while internal groups keep staff-only content behind a login. For readers outside your company, like partners or verified customers, you can pass permission groups in a JWT so they see a tailored slice of the knowledge base without ever creating an account. If this internal-external divide is new to you, our guide to internal versus external knowledge bases is a good companion read.
What are the best practices for structuring groups?
A few habits keep your setup clean as the team grows.
- Apply least privilege. Give a group the narrowest content scope its members need, and remember membership can be read-only (view but not edit) or full-access (view and edit). Reach for read-only whenever a team needs to reference content it should not change.
- Map groups to categories, not single articles. Assign a group to a whole category and new articles created inside it inherit that group automatically. You can even enforce permissions on all descendant content so a section stays locked down as it grows.
- Keep the number of groups small. A handful of well-named groups is easier to reason about than twenty overlapping ones. If two groups almost always contain the same people, merge them.
- Name groups for the team, not the person. “Support L2” survives staff changes. “Priya’s team” does not.
- Avoid confusing overlap. Because a user can be in several groups and an article can carry several groups, access stacks up fast. Sketch out who ends up seeing what before you go live.
Here are three example setups to adapt.
| Group | Who’s in it | What they can see or edit | When to use it |
|---|---|---|---|
| Support L1 | Front-line support agents | Read and edit customer-facing how-tos and FAQs; no internal runbooks | You want agents improving public docs but shielded from internal-only content |
| Product (internal) | Product managers and engineers | Full access to the internal roadmap and spec categories; read-only on marketing docs | Departmental internal content that should not reach customers |
| Verified partners | External partners (via JWT) | View-only access to a partner integration category, no account needed | Sharing gated docs with people outside your company |
How do good groups make you faster?
The payoff is less day-to-day gatekeeping. When a new support agent joins, you drop them into “Support L1” and they instantly have the right view, instead of you configuring access article by article. Offboarding is just as quick: removing someone from their groups pulls their access in one move.
Get this right and permissions fade into the background. New teammates land in the correct view on day one, sensitive content stays put, and you delegate editing without worrying about who might see what. That is the real win: your knowledge base scales with the team instead of turning into an access headache.
