How to use this knowledge base requirements checklist
This checklist turns a vague wish for a better wiki into a written list of requirements, each with a reason it matters and a way to verify it. Work through it in order: content structure and editors first, then permissions, SSO, search, history, attachments, templates, export, integrations and migration. For every item, record who needs it, what happens if the platform cannot meet it, and how you will test it. A team leaving Confluence, Notion or an aging internal wiki usually discovers that its real requirements are about page ownership, group-based access and old content that must move, not about features on a vendor comparison sheet.
Because the decision between BookStack, Outline and XWiki depends on these answers, treat the checklist as a starting point for a written scope, not a purchase decision. Several items cannot be judged from documentation alone. Permissions that depend on directory groups, search quality on your own vocabulary, and whether attachment history survives a move all need a test. Run a pilot with a representative set of real spaces, including your messiest pages, a restricted HR or security area and a sample of attachments. Confirm license terms with each vendor before the pilot, because a platform that fails a requirement during testing is cheaper to discover than one that fails after migration.
Keep the output of this exercise as a signed requirements list that a partner can price against. Each unresolved item should carry an owner and a decision date. Ask prospective implementation partners to respond to the same list in writing, so that scope, deliverables and timelines can be agreed before any work begins. Vague requirements produce vague quotes, and most of the cost surprises in wiki projects come from requirements that were assumed rather than checked.
Functional requirements every knowledge base needs to meet
This table lists the functional requirements a self-hosted wiki must meet, why each matters to the business, and what to test in a pilot before committing to BookStack, XWiki or Outline. Read each row as a pilot test: the platform is only accepted for a requirement once your own content and users have passed the check.
| Requirement | Why it matters to the business | How to verify in a pilot |
|---|---|---|
| Content structure (books, chapters, pages, shelves or spaces) | Teams find procedures faster when the hierarchy mirrors how the business is organized. A flat structure becomes unmanageable as page counts grow. | Load a realistic sample of your departments and runbooks, then test whether a new hire can locate three known procedures within a few clicks using only navigation and search. |
| Editor modes (WYSIWYG, Markdown, diagrams) | Non-technical staff need a visual editor, while engineering teams often expect Markdown and embedded diagrams. Mismatched editors cause inconsistent pages. | Have one business editor and one engineer each create and edit a page with tables, images and a diagram. Confirm that content round-trips without formatting loss. |
| Reader and editor roles | Separating who can publish from who can only read protects approved procedures from accidental change. | Create reader, editor and approver accounts from a test directory group. Confirm each role can perform only its intended actions, including on a page it did not create. |
| Page and space permissions | Sensitive pages such as HR, legal or security content must stay hidden from people outside their scope. | Restrict one page and one space to a test group. Log in as a user outside the group and confirm the page is absent from navigation, search results and direct links. |
| Page history and revision restore | Version history supports audit questions about what a procedure said on a given date and allows recovery from bad edits. | Edit a page several times, restore an earlier revision, and confirm who made each change and when. Check whether history survives a page move or migration. |
| Attachments and file handling | Policy PDFs, diagrams and spreadsheets often live alongside pages. Attachments without controls create a second, unmanaged document store. | Upload files of the sizes and types your teams use. Confirm that attachment permissions follow the parent page and that attachment versions, if kept, are visible to auditors. |
| Templates and controlled documents | Standard templates make runbooks, SOPs and policies consistent and easier to review. | Create a template for a policy or runbook, instantiate it twice, and confirm that the template can be restricted to approved editors. |
| Search and access-aware results | Search must return only pages a user can read, or it leaks titles and excerpts of restricted content. | Search for a term that appears only on a restricted page as an outside user. Confirm no title, excerpt or count appears. Also test search quality on a sample of real questions. |
| Export and offline copies | Exports support legal holds, disaster recovery and exit planning, and keep critical runbooks readable during outages. | Export a space in each offered format and confirm that pages, attachments and internal links survive. Restore the export into a clean instance to verify it. |
How content structure and permissions shape the platform choice
The permission model has to be designed before any content moves, because the two most likely platforms organize access differently and a migration will copy whatever rules exist today. BookStack arranges content as books, chapters and pages, grouped on shelves, and its role and permission system is the mechanism that decides who sees what. Permissions can be set at the shelf, book, chapter and page level, so a team that wants a restricted page inside an otherwise open book needs to confirm that the page-level override behaves as expected for the roles it will use. XWiki takes a different approach: content lives in spaces and pages, and rights are assigned through its own rights model, while features such as SSO application support, file management and connectors come from optional applications, some of which are only listed in XWiki Pro. Readers should map their current Confluence or Notion spaces to each platform's structure on paper before deciding.
Before a pilot import, write down the access rules the business actually needs: which spaces are company-wide, which are restricted to a department, and which individual pages must be hidden from people who can otherwise read their parent. Then test those cases in a staging instance with real directory groups, not only with local test accounts. Confirm with the vendor or the implementation partner how per-page restrictions are stored, whether they survive import, and whether group membership from LDAP, SAML or OIDC maps directly onto the platform's roles. Ask how a migration tool treats permissions it cannot map, because silent defaults can widen access. Illustrative example: a Confluence space restricted to a legal team that is imported into an open space would be readable by everyone, and no one would be alerted by the import itself.
Once the permission design is agreed, the same design becomes the basis for an audit. Ask the platform to show, for a sample of sensitive pages, the complete list of users and groups with read and edit rights, and confirm that this report can be produced without manual inspection of each page. Record which permission changes are logged and how long those logs are kept in your environment, since the answer depends on configuration and the logging capabilities of the chosen platform rather than on the wiki's marketing. A permission model that is documented, tested and reproducible in a second environment is far easier to defend in a review than one that exists only in the admin interface.
Security requirements to write into the scope
A knowledge base holds policies, runbooks and sometimes sensitive internal material, so its security requirements belong in the scope from the start. The cards below cover identity, transport, audit, platform patching, recovery and sharing, and each names what to confirm with the vendor or in your own environment before you commit.
SSO through OIDC, SAML2 or LDAP
Sign-in should come from your identity provider, so that joiners, leavers and group changes take effect in the wiki without manual account work. BookStack documents OIDC, SAML2 and LDAP sign-in, and XWiki's OIDC support is available through the xwiki-contrib extension, which should be confirmed for your XWiki version. Check how directory groups map to wiki roles, what happens to local accounts when SSO is enabled, and whether break-glass admin access exists for identity outages.
Enforced multi-factor authentication by role
Administrators and editors of policy or runbook spaces should face stronger sign-in requirements than casual readers. BookStack includes built-in multi-factor authentication that can be enforced per role. For XWiki, confirm whether MFA is provided by your identity provider or by an extension, and test enforcement for each role group before go-live.
Encryption in transit
Pages, attachments and session cookies cross the network, and the HIPAA Security Rule requires technical measures against unauthorized access to ePHI sent over electronic networks. Require TLS end to end, including between a reverse proxy and the application, and confirm HSTS, certificate management and how internal links to the identity provider are protected. Ask the vendor which ciphers and protocol versions the default configuration uses.
Audit logging of reads and edits
The HIPAA Security Rule requires audit controls that record and examine activity in systems holding ePHI, and similar questions arise for policy evidence in other regimes. Most wikis log edits clearly, but page views and attachment downloads are often not recorded by default. Ask whether read events are logged, where logs are stored, how long they are kept, and whether they can be forwarded to your SIEM.
Patching the PHP, Java and database stack
BookStack runs on PHP and needs MySQL 8.0 or MariaDB 10.6 or later, while XWiki runs on Tomcat with MySQL, PostgreSQL or MariaDB. Each layer carries its own security updates, so the scope should name who applies them, how often, and how a vendor release is tested before production. Confirm the supported PHP or Java versions for the release you choose and the upgrade path for the database engine.
Backup and restore of database and attachments
A wiki's database holds page structure, permissions and history, while attachments live on separate storage, so a backup must cover both and be tested as a restore. Define recovery objectives in the scope, store copies outside the primary cluster, and confirm that a restore brings back permissions and attachment links intact. Ask how page history and attachment history are included in backups, since migration tools may not carry both.
Restricting external sharing
Public share links and guest accounts can expose internal runbooks or personal data outside the organization. Decide which spaces may be shared externally, who may create share links, and whether anonymous read access is disabled at the instance level. Confirm in the product settings how guest access interacts with directory groups, and test that a restricted space cannot be reached by an unauthenticated visitor.
Migration requirements from Confluence or Notion
This sequence turns a Confluence or Notion estate into a reviewed inventory, a tested migration and a signed-off reconciliation, so you know what moved, what was left behind and who checked it. Each step ends with evidence you can hand to the project owner before the next step begins.
Inventory spaces, pages and attachments
Start by exporting a complete list of spaces or workspaces, page counts, page sizes, attachment counts and page owners from the source system. Mark stale spaces, personal drafts and duplicate pages as candidates for archive rather than migration. The content owner for each space confirms the list. You know this step is done when every space has a disposition (migrate, archive or delete) and the owner has signed off on it in writing.
Map users, groups and permissions
Build a mapping table that links each source user and group to the identity source the new wiki will use, such as your directory through LDAP, SAML or OIDC. Record how Confluence space permissions and Notion page or teamspace access translate into the target model of spaces, books or pages. Flag any group that does not exist in your directory and any permission that the target cannot express. The security owner reviews the table. You know this step is done when every active user resolves to one account and every permission exception has a decision.
Decide which history must survive
Decide with the records or compliance owner which page history is needed for audit, approval or dispute purposes. Confluence Migrator Pro, the XWiki SAS tool for Confluence, is documented as keeping page history but not attachment history. If your retention rules require attachment versions, record that gap now and plan how those versions will be preserved separately, such as in an archive export. Confirm the tool's behavior with the vendor against your own test data. You know this step is done when the retention decision is written down and each history gap has a named owner.
Build and migrate a representative test set
Assemble a test set that covers each space type, a page with deep nesting, pages with macros or embedded diagrams, restricted pages, and large attachments. Confluence Migrator Pro's trial is limited to 30 pages per migration, so keep the test set within that limit or confirm pricing and scope with the vendor before you run a larger sample. Run the migration into a non-production instance and log every warning and failed object. You know this step is done when the test set migrates with a log that the migration owner has reviewed and each failure has a fix or an accepted exception.
Check Notion exports for links and structure
If the source is Notion, run the export and review it separately from any Confluence step. Check that internal links between pages resolve after import, that databases and linked views are either converted to tables or documented as lost, that nested page hierarchy matches the intended book and chapter structure, and that embedded files arrive with their pages. Confirm which of these elements your chosen target platform imports cleanly by testing it, since tool behavior varies by target. You know this step is done when a sample of cross-page links and nested pages is checked by hand and the results are recorded.
Reconcile attachments against source counts
Compare attachment counts, file sizes and checksums or file names between the source and target for every migrated space. Reconcile the totals against the inventory from the first step, and list any attachment that is missing, renamed, oversized or replaced by a placeholder. Decide with the content owner whether each gap is fixed, accepted or handled by a manual upload. You know this step is done when the attachment reconciliation report shows zero unexplained differences and each accepted gap has an approver.
Run the full migration and sign off
Schedule the full migration in a window agreed with the content owners, freeze edits in the source for the affected spaces, and run the migration against the production target. Repeat the inventory, permission and attachment checks on the full data set and compare the results with the test-set findings. Keep the source system read-only for a period agreed in your change plan so users can verify content. You know this step is done when reconciliation reports for pages, users, permissions and attachments are signed by the migration owner and the business owners of each space.
Operational requirements and how to verify them
This table lists the operational requirements a knowledge base must meet after go-live, the risk when each is missing, and the check to run before you commit. Use it with BookStack or XWiki as the candidate platform, and treat every version number as a point-in-time reference to confirm against the vendor's current release notes.
| Requirement | Risk if missing | Verification step |
|---|---|---|
| Hosting model and placement (own cloud account, data center or air-gapped network, with the wiki kept outside the main cluster if it is also a runbook source) | Wiki goes down with the systems it documents, or data leaves the controlled boundary | Confirm in writing where the application, database, attachments and backups run, and test access to the wiki during a simulated cluster outage |
| Supported database versions (BookStack needs PHP 8.2 or later with MySQL 8.0 or MariaDB 10.6 or later) | Install fails or runs on an unsupported stack that the upgrade path will not cover | Check the database and PHP versions against the installation docs before build, and record them in the build sheet |
| XWiki release line: stable, LTS or intermediate LTS (18.8.0 stable, 17.10.14 LTS and 18.4.7 intermediate LTS at time of research) | Stable line forces frequent upgrades; an LTS line that ages out leaves extensions and security fixes behind | Decide the line with the platform owner, confirm current tags in the official image library, and document the planned move to the next line |
| Upgrade cadence and tested upgrade path, including extension compatibility | Upgrades break macros, SSO connectors or custom themes, and nobody notices until users report it | Require a staging upgrade test on a copy of production data, with a written rollback step and a list of extensions checked |
| Backups of the database, attachments and configuration, with restore testing | Page history or attachments are lost in an incident, or backups exist but cannot be restored | Ask for the backup schedule and retention, then run a timed restore into a separate environment and record the result |
| Monitoring and alerting (availability, disk growth for attachments, failed logins, certificate expiry) | Outages or full disks go unnoticed until users complain | Confirm which metrics and logs are collected, who receives alerts, and test one alert end to end |
| Extension and plugin management (approval, versioning and removal process) | Unreviewed extensions add code paths, licensing questions or compatibility failures | Keep an approved extension list with versions, owners and the license of each, and review it at every upgrade |
| Support model and response expectations (vendor support, partner retainer or internal team) | Nobody owns a production fault at night, or support terms do not match the license tier in use | Get the support tier, named contacts and response terms in writing, and confirm which tier covers the features you plan to use |
| Documentation availability (admin guide, runbook for the wiki itself, and an offline copy of key procedures) | Administrators cannot recover the wiki without the people who built it | Require admin documentation, a recovery runbook and an export of critical pages stored outside the wiki, then test that a second administrator can follow them |
What buyers ask before hiring help for a knowledge base
How much effort does a requirements checklist and pilot take?
The effort depends on how many spaces, user groups and permission rules the organization has, and on how many people must agree on them. A checklist review covers content structure, editor and reader roles, SSO, search, history, attachments, export and integrations, so the more systems and departments involved, the longer the review. A pilot adds effort in proportion to how many real spaces are tested, how many identity groups are mapped and how many people test the editing and reading experience. Ask any partner for a written scope that lists the spaces, groups, integrations and test users included, because that list drives the quote more than the platform choice does.
What does a Confluence migration need from our business teams?
Migration work needs decisions from the business more than from engineering. Content owners must decide which spaces, pages and attachments are current, which are archived and which should not move at all. Security or HR leads must confirm who may read each space, because Confluence groups and permissions do not always map cleanly to a new platform. Someone with sign-off authority must approve the test migration and the cutover date, and must confirm how page history and attachment history will be treated. Confluence Migrator Pro from XWiki SAS, which the XWiki Store lists at a starting price of 2000 EUR, migrates spaces, pages, users, groups, permissions and attachments and keeps page history but not attachment history. Confirm that limitation with the vendor before you plan around it.
Can our internal IT staff run a self-hosted wiki on their own?
Many teams can run a wiki with existing staff, but the answer depends on skills and time rather than on the software being hard to install. Day-to-day work includes applying upgrades, backing up the database and attachments, monitoring the service, rotating certificates, managing SSO group mappings and restoring from backup. BookStack requires PHP 8.2 or later with MySQL 8.0 or MariaDB 10.6 or later, and XWiki runs on Tomcat with MySQL, PostgreSQL or MariaDB, so the team needs people who can maintain those stacks. Decide who owns each task, how often upgrades happen and who answers when the wiki is down. Some organizations keep administration in house and bring in a partner only for the initial build or upgrades.
Which knowledge base costs are one-time and which recur?
One-time costs usually include the requirements review, the pilot, the initial configuration, SSO and permission design, the content migration and staff training. Recurring costs include hosting, storage, backups, monitoring, software support subscriptions where chosen, upgrades, and the time staff spend on administration. Licensing differs by product: BookStack is MIT licensed, so the software itself carries no license fee, while XWiki Standard is free and XWiki Pro and support subscriptions are paid. XWiki SAS lists consulting at 1200 EUR per day, which requires a Business or Enterprise support plan, so that rate applies only under that plan. Ask for a quote that splits one-time work from annual support and hosting, and that shows the subscription tier and user count it assumes.
How do license terms change which wiki we can choose?
License terms decide what you can build and offer, not only what you pay. BookStack is MIT licensed and XWiki Standard is free open source under LGPL 2.1 or later, so both allow internal use and modification without a commercial license. Outline is licensed under the Business Source License 1.1, and its additional use grant forbids offering a commercial Document Service, which matters if you plan to host it for customers or sell access to documentation. Wiki.js is AGPL-3.0, which requires source sharing when users interact with a modified version over a network. Have counsel confirm how each license applies to your intended use, including any hosting for affiliates, contractors or customers.
Which SSO and permission details should we verify before a pilot?
Verify the identity protocol, the group source and the permission model before the pilot begins. BookStack supports OIDC, SAML2 and LDAP sign-in, with multi-factor authentication that can be enforced per role. XWiki supports SSO through its extensions, and its community OIDC module is listed in the XWiki contrib repository, so confirm the version and support status for your release. Check how directory groups map to wiki roles, how deprovisioning removes access, and whether page-level restrictions for HR or legal content behave as expected. Test with real group memberships rather than a few admin accounts, because access errors usually appear with ordinary users.
What drives the scope of a knowledge base implementation?
Scope grows with the number of content sources, integrations, user groups and compliance obligations. A small team with one wiki, one identity provider and no migration has a narrow scope. Scope widens with a Confluence or Notion import, with search tuning across many spaces, with integrations into ticketing or chat, with sensitive spaces that need audit of who can read what, and with retention rules tied to a regulation. Ask any partner to list which of these are in scope, which are excluded and which will be decided during the requirements phase, so the agreed scope reflects the real work.
Questions that separate one knowledge base platform from another
Knowledge base platforms look similar in demos and differ sharply in permissions, identity, developer access, migration, licensing and upgrades. The cards below turn those differences into questions you can put to each vendor or implementation partner. Ask for every answer in writing and tied to your own identity provider, content volume and hosting model.
Per-page permissions model
Confirm whether access can be set per page, per chapter or book, or only per space, and whether inherited permissions can be overridden without breaking search. BookStack organizes content into books, chapters and pages on shelves and includes a full role and permission system. XWiki's rights model is more granular and is the stronger fit where departments or HR and legal pages share one wiki. Ask for a test plan that shows what a restricted reader can see in search results, page titles and attachments.
Native SSO protocols
List which protocols each platform supports without add-ons: OIDC, SAML2 or LDAP. BookStack supports OIDC, SAML2 and LDAP sign-in and can enforce multi-factor authentication per role. XWiki's Active Directory and Azure Active Directory SSO applications sit in XWiki Pro, while OIDC is available through the community xwiki-contrib extension. Ask how group membership maps to spaces and whether deprovisioning removes access on the same day a user leaves.
Markdown and API access
Engineering teams often need Markdown import and export, a documented REST API for automation, and webhooks for publishing from pipelines. BookStack offers a WYSIWYG editor with an optional Markdown editor and built-in diagrams.net diagrams. Ask each vendor which operations the API exposes, whether it can create, update and export pages in bulk, and how API tokens are scoped and rotated. Confirm these answers against the version you plan to deploy.
History and attachment migration
Migration from Confluence or Notion usually fails on metadata, not body text. Confluence Migrator Pro from XWiki SAS moves spaces, pages, users, groups, permissions, attachments and metadata, and keeps page history but not attachment history. Ask which of your page versions, comments, labels, restrictions and attachment versions survive the move, and request a trial run on one real space before you accept a scope. Notion exports are a separate path and need their own test.
License restrictions on commercial use
Read the license before you assume a platform can be offered to others. Outline is licensed under the Business Source License 1.1, and its additional use grant forbids using it to offer a commercial Document Service. That matters if you host a wiki for customers, partners or subsidiaries. BookStack is MIT licensed and XWiki Standard is LGPL-based. Ask your counsel to confirm how each license applies to your deployment model and to any paid extensions you plan to add.
Upgrade testing and release lines
Wiki upgrades touch schema, plugins and authentication, so ask how each vendor separates stable and long-term support releases. XWiki publishes a stable line, a long-term support line and an intermediate LTS line, which lets you stay on a supported branch for longer. Ask the partner to show a staging environment, a restore test from backup, a checklist for extensions and a rollback path. Request written answers on who tests upgrades before they reach your production wiki.
How DeployOpen scopes and delivers knowledge base selection and implementation
DeployOpen turns a knowledge base requirements checklist into a written scope before any platform is installed. The work covers platform selection among BookStack, XWiki and other open-source options, then implementation inside your own cloud accounts, data centers or air-gapped networks. Engagements are fixed-scope, with deliverables and timelines agreed in writing first.
How we scope
- Workshop with content owners to list spaces, editors, readers and the pages that need restricted access
- Written mapping of SSO, search, page history, attachment, template and export requirements to each candidate platform
- Written scope stating which migration sources, integrations and hosting environment are covered, with a quote following from it
How we build
- Install the chosen wiki in your environment, including database, reverse proxy and backup configuration
- Configure SSO against your identity provider, role mapping and per-space or per-page permissions as agreed in scope
- Test permissions with named test accounts, check search and attachment behavior, and run a pilot migration where in scope
How we hand over
- Deliver installation, configuration and permission model documentation that your administrators can maintain
- Provide a runbook for upgrades, backups and restores, and for recovering access if the identity provider is unavailable
- Walk administrators and content owners through editing, approval and access review procedures before sign-off
How we support
- Ongoing support, upgrades and periodic access reviews are available as a retainer after handover
- Upgrade planning follows the vendor's release line, with changes tested in a staging copy before production
- Support scope, response expectations and review cadence are written into the retainer agreement, not assumed
