Internal vs public docs: structuring documentation for a SaaS team

Most SaaS teams end up with documentation in too many places: a help centre for customers, a wiki for the team, a few shared documents for sales, and a lot of knowledge in chat threads. Each tool made sense when it was added, but together they make information hard to find and easy to let go out of date. This guide covers how to decide what goes where, and how to structure both so they stay useful as you grow.

Know your audiences

Documentation works best when every page is written for one audience. For most SaaS companies there are three:

• Customers, who want to get something done in your product
• Your team, who need to know how the company works and how to support customers
• Developers or partners, who integrate with your product through an API or integrations

Customers and developers read your public documentation. Your team reads your internal documentation. Mixing them leads to customer docs full of jargon, or internal knowledge that's accidentally public.

What belongs in public docs

Public docs should help customers succeed without contacting you:

• Getting started guides for new customers
• How-to guides, with one task per page
• Troubleshooting for common problems and error messages
• FAQs about billing, accounts and limits
• API references and integration guides, if you offer them
• A changelog, so customers can see what's new

What belongs in internal docs

Internal docs help your team work consistently and onboard new people quickly:

• Onboarding for new team members, with links to everything they need to read
• Processes, covering how you handle releases, refunds, account changes and customer requests
• Support playbooks for common tickets, including approved workarounds
• Runbooks for engineering tasks and incidents
• Decisions, recording what you decided, why, and what you considered

Handle the grey areas page by page

Some content sits between the two. Known issues, upcoming features and detailed setup notes might be useful to customers but sensitive in places. Rather than forcing everything into one bucket, decide page by page. With per-page permissions, a page can start internal and be made public once it's ready, without moving it or copying it somewhere else.

A useful rule: if a customer seeing the page would be fine, and helpful, make it public. If it includes internal reasoning, customer names, or anything you'd rather not commit to publicly, keep it internal.

Structure by audience, then by topic

Start with a separate area for each audience, then organise each one by topic:

1. Customer docs: getting started, then a section per product area, then troubleshooting and FAQs
2. Developer docs: authentication, API reference and integration guides
3. Team handbook: onboarding, company processes and policies
4. Support: playbooks, known issues and escalation paths
5. Engineering: runbooks, architecture notes and incident reviews

Nest related pages inside each section. A top level with five clear sections is far easier to navigate than a flat list of a hundred pages.

Write each page for one job

Whoever the reader is, they arrive with a question. Help them answer it quickly:

• Use task-based titles, like "Invite a teammate" rather than "User management".
• Put the answer first, then the detail.
• Keep steps numbered and short.
• Link to related pages instead of repeating them, so there's one version of each fact.

For more on writing pages like this, see how to write documentation people actually use.

Make keeping docs current part of the work

Documentation goes out of date when it's treated as a separate task for later. A few habits help:

• Add docs to your definition of done. A feature isn't finished until its guide is updated.
• Give each section an owner who reviews it regularly.
• Look at your most-viewed pages to see what matters most, and improve those first.
• Use version history, so anyone can see what changed and why.

A first-month plan

1. Week 1: List the top 10 questions customers ask and the top 10 things new hires ask. Set up separate customer and team areas.
2. Week 2: Write the customer getting started guide and the 10 most common how-to guides.
3. Week 3: Write your team onboarding page and your 5 most important processes.
4. Week 4: Link the customer docs from your app, emails and support replies, and add "update the docs" to your release checklist.

If your docs are spread across several tools today, keeping customer docs and your internal wiki in one place, with permissions deciding what's public, removes a lot of that sprawl. See how Docvora works for SaaS teams.