On February 25, we hosted our webinar “Building a knowledge base that lasts: How to structure, maintain, and scale your documentation”, led by Neculai Dascălița and Cédric Lamblin, Account Managers at XWiki who work closely with organizations of all sizes to design and improve their documentation platforms.

The session focused on a pattern many teams experience. Documentation works well at the beginning. As teams grow and content expands, structure weakens, ownership becomes unclear, search becomes less reliable, and outdated information accumulates. What once helped collaboration slowly turns into friction.

Rather than treating documentation as a collection of pages, we discussed it as infrastructure. Infrastructure requires architecture, governance, visibility, and a platform designed to support long term growth.

Throughout the webinar, we shared practical strategies and real tools developed within XWiki to show how your organization can structure internal and external documentation, enforce consistency, and keep knowledge usable as it scales.

Below you will find this webinar's recording, key takeaways, and a full recap of the Q\&A session.

Watch the video

Key takeaways

#1 Documentation needs architecture

Documentation does not scale without structure.

Before selecting tools or reorganizing content, organizations need to define how documentation should be structured.

  • Should you organize it by team, by product, or by business domain?
  • Where do isolation boundaries belong?
  • What content should be internal, public, or shared with clients?
  • How should you handle multilingual documentation?

XWiki supports multiple architectural models:

  • Nested page hierarchies for logical organization within one wiki
  • Spaces for functional grouping
  • Subwikis for stronger technical and organizational isolation
  • Cross-wiki search when centralized visibility is required

This allows documentation to be structured intentionally instead of constrained by tooling.

Scalability is a design decision.

#2 Governance prevents documentation decay

Most documentation does not fail because of bad writing. It fails because there is no governance model.

Documentation becomes unreliable when nobody is responsible for it, when teams invent their own formats, when outdated content remains visible, and when there is no visibility into what is being used.

XWiki supports governance through structured document types created with:

With Analytics Application (Pro), teams can monitor usage patterns and identify outdated or unused content.

Documentation health can be measured and managed, not assumed.

#3 Structure enables scalability

When teams say “Search doesn’t work,” the real issue is usually structure and metadata.

Large documentation platforms often suffer from duplication, inconsistent terminology, and unclear hierarchies. In these cases, improving search alone will not solve the problem.

XWiki supports structured data models, metadata driven navigation, faceted search, and cross subwiki search. When structure and metadata are defined properly, search becomes reliable and predictable.

Search becomes reliable when structure is defined.

#4 Documentation should connect to execution

Documentation that lives in isolation becomes outdated.

In the webinar, we showed how XWiki developed the OpenProject Integration (Pro) to connect documentation pages with real work packages. We also showcased the Collabora Connector Application (Pro). It allows users to collaboratively edit XWiki attachments from the office suite, such as documents, spreadsheets, or presentations, and to create new ones on the fly and save them directly as page attachments.

When documentation is embedded in workflows, it remains relevant.

Q&A session

Below is a complete recap of the questions asked during the session.

  • Does XWiki store information in a database or as plain text?

    XWiki stores its content in a relational database such as PostgreSQL or MySQL. Page content, metadata, version history, permissions, and structured objects are stored in the database. Attachments are stored on the filesystem and linked to their respective pages.

    Exporting content is straightforward. XWiki provides full site export and space export in XML format, making it easy to move content between instances. You can also use the REST API, generate PDF or Office exports, or rely on database backups.

  • How does using several subwikis impact updates of XWiki and installed extensions?

    XWiki comes with a distribution mechanism that includes a Distribution Wizard. After a system upgrade, this wizard allows you to go through the extension upgrade process.

    Since subwikis are isolated environments, you need to run this distribution process for each subwiki. However, scripting tools can automate this across multiple subwikis when needed.

  • Is there a way to integrate Markdown files within the XWiki page structure?

    Yes. XWiki provides a Markdown Syntax extension that supports CommonMark and GitHub-flavored Markdown.

    Once the extension is installed, you can activate Markdown syntax on a page and use it directly.

  • If you install a paid extension only in one subwiki, is the price calculated based on the users in that subwiki or the entire system?

    Licensing for paid extensions is based on the total number of users in the entire system, not only on the subwiki where the extension is installed.

  • Is there a connector available for GitLab issues?

    Currently, there is no native connector for GitLab issues.

    However, as long as a tool provides a public and documented API, integration with XWiki is technically possible. XWiki has a foundation for linking to external project management tools, and such an integration could either be custom-developed or sponsored.

  • I see the word “space” in some XWiki documentation pages. Does XWiki support spaces such as in Confluence?

    XWiki does not implement spaces in exactly the same way as Confluence. Instead, it provides 2 structural models: nested pages and subwikis.

    Nested pages allow hierarchical organization within a single wiki. Subwikis provide stronger isolation when departments, clients, or business units require separation.

    You can assign administrative rights to a subtree of pages to achieve behavior similar to Confluence spaces. However, technically speaking, the implementation differs, particularly in how rights inheritance and isolation are handled.

  • Are there ways to monitor outdated content, including planning and push notifications?

    Yes. A community extension called Review Pages allows teams to define review cycles and track documentation that requires validation.

    In addition, modification dates and activity history are tracked by default. When combined with tools such as Analytics Application (Pro), teams can identify inactive or outdated content and implement structured review processes.

  • How can I achieve a similar restrict page concept for subpages, like in Confluence, without giving every user admin rights?

    In XWiki, rights are defined at higher levels, typically at the wiki level. These rights apply by default.

    Then on subpages or subpages and children, you can define overrides to grant or deny specific permissions.

    Administrative rights granted at a higher level cannot be denied at a lower level. If a user is defined as an administrator for a given scope, those rights remain effective throughout that scope. This differs slightly from Confluence’s permission model.

    Unlike Confluence, in XWiki you can open view rights defined in a parent page for certain subpages.

    Learn more in our XWiki vs. Confluence comparison.

  • What about search and subwikis? Is it possible to search through all subwikis at once?

    By default, if your search is triggered in the main wiki (also called "farm level"), content from all subwikis will be offered. If your trigger a search in a subwiki, only results coming from this subwiki will be displayed.

    Some clients have implemented customizations to enable cross-subwikis search when needed.

  • Does XWiki offer an MCP endpoint?

    At the moment, XWiki does not offer support for the Model Context Protocol (MCP), a protocol used to interact with large language models.

    There is an ongoing project called WAISE, currently in beta, which enables integration with large language models that you deploy yourself. MCP support may be considered in the future, potentially through sponsorship, but there is no short-term roadmap commitment.

  • Is it possible to show calendars from a CalDAV server like Microsoft Exchange or dynamic ICS files?

    Using the Calendar Application (Pro), XWiki can display ICS files.

    Dynamic subscription to certain external calendars, such as Outlook, may be possible, although limitations may exist depending on the specific system.

    For more complex integrations like Exchange or Indico, further verification may be required depending on the use case.

  • Are there ways to open parts of the documentation for public access, such as a product handbook?

    Yes. You can keep the entire wiki private and selectively open certain pages to unregistered users, as detailed in our documentation. Alternatively, you can create a separate public subwiki dedicated to product documentation.

  • Is there a way to migrate wikis from Redmine to XWiki without losing relations and images?

    There is no native Redmine importer.

    However, if Redmine allows content export in a usable format, XWiki’s Filter Stream extension can potentially import the content.

    Feasibility depends on the quality and format of the exported data and the ability to configure the import process.

  • Is it possible to move all attachment files in one click instead of moving them one by one?

    Attachments in XWiki are always associated with a page.

    If you move a page, its attachments move with it. There is no dedicated extension specifically for bulk-moving attachments independently of pages. However, scripting capabilities exist, and community-provided scripts are available in the XWiki Snippets repository.

    In many cases, perceived attachment limitations can be solved by using features such as the View File macro, which allows displaying attachments stored elsewhere.

  • How neatly does XWiki integrate with openDesk?

    XWiki is one of the core components of openDesk. Improvements developed within the openDesk ecosystem are contributed back to the open-source XWiki project, ensuring transparency and sustainability.

  • We are switching from JSM to GLPI. Are you planning on doing an integration so XWiki can replace the GLPI knowledge base?

    There is no dedicated GLPI connector at the moment. However, XWiki’s API-based architecture makes integration technically feasible when required.

  • We’re currently on Confluence. If we move, how much pain are we looking at?

    Migration complexity depends on instance size, macro usage, permissions, and customizations. XWiki provides open-source importers and a Confluence Migration Toolkit. For larger or more complex environments, professional services help reduce risk and ensure smoother transitions.

    Migration is about preserving structure and governance, not just moving pages. To ensure your team has a smooth migration process, we gathered a transparent, comprehensive and easy-to-follow comparison between commonly used Confluence macros and their alternatives in XWiki.

  • We already use OpenProject. Is there a clean way to connect documentation with actual project work?

    Yes. Documentation pages can embed OpenProject work packages, and bidirectional links can be created between documentation and project execution. This keeps knowledge connected to real operational workflows.

  • We have 6,000 pages and honestly do not know which ones are still relevant. Is there a way to see what is actually being used?

    Yes. Analytics Application (Pro) provides usage metrics, activity dashboards, and last modification data. You can identify inactive or unused pages systematically instead of reviewing everything manually.

  • How does XWiki handle public wikis where anonymous users can access content without an account?

    Anonymous read access is fully supported. As mentioned in our answer to Q12, permissions can be configured precisely to expose certain areas publicly while keeping others restricted.

  • Can we enforce documentation templates so teams do not invent their own formats?

    Yes. You can enforce page templates or create structured document types using App Within Minutes. This ensures consistent formats for runbooks, incident reports, policies, or any other documentation type.

  • We have internal docs, client docs, and product docs. Should those live in the same place, or do they require separate systems?

    It depends on governance and security requirements. XWiki allows logical separation within one wiki or stronger isolation through subwikis. You can maintain one installation while separating content appropriately.

  • How do we identify outdated documentation without manually checking everything?

    Analytics dashboards, metadata tracking, review workflows, and notification systems allow you to detect stale content systematically. Maintenance becomes structured rather than reactive.

  • Can we create structured pages for runbooks or incident reports instead of relying on free text?

    Yes. Structured document types can be created using App Within Minutes. You can define fields, enforce formats, and improve consistency, making documentation easier to maintain and search.

  • Search is killing us. People say the documentation exists, but nobody can find it. What makes search actually work at scale?

    Search works when structure exists. Clear hierarchies, consistent metadata, proper permissions, and defined document types are essential. XWiki supports faceted search and structured indexing. When architecture is intentional, search becomes predictable and reliable.

Final thoughts

Documentation that lasts is not accidental.

It requires clear architecture, defined ownership, structured content, visibility into usage, and integration with operational tools.

XWiki has been 100% open source since 2004 and is used by more than 1,000 organizations worldwide. It is designed to support documentation as long term infrastructure, not just a collection of pages.

That wraps up our webinar, Building a knowledge base that lasts. If you would like to explore how XWiki can support your documentation strategy, contact us at contact@xwiki.com or book a call with our team.