Implementing Mediawiki as a documentation platform

How Genesys uses Mediawiki


Xavier Roy

I work at Genesys as a Staff Technical Writer.

My role involves writing, editing, and content engineering.

/now interested in personal knowledge management, role-playing games, and neuroscience…

How we chose Mediawiki?

In the beginning… (circa 2015)

the final choice was..

Proof of Concept


There were still a lot of things missing

Improvements to Mediawiki

Automation for Release Notes

From JIRA to Mediawiki

JIRA Query ➡️ categorise ticket information ➡️ convert to wikitext ➡️ create Release Note (New, Resolved, and Known Issues)

Adding semantics to content

  • started using Cargo (a MW extension) to store and query metadata.
  • applied structure to content.
  • allowed us to develop different view models to display content.

Configuration Options

  • import XML content from dev teams to Mediawiki.
  • build a content model for an option and store info in Cargo.
  • present data in a filterable model to locate any configuration option across products.
  • view content as a pop-up or in a special reference guide.

Supported Operating Environment Reference

  • the single source of truth for all supported software like OSes, databases, browsers, third-party tools.

  • used by customers and internal teams.

  • Form-based entry because content is entered by Product Managers.

  • Cargo data is used to build individual product-specific information and also across all products.


MintyDocs is a MW extension that was built specifically for product documentation. It is an imporved & restructured upgrade from PonyDocs extension (PD had no active development since 2017 and considered abandoned).

MintyDocs is available under GNU General Public License for others to use.

What MintyDocs gives us

  • Form-based authoring via Page Forms extension
  • Metadata and structured data via Cargo extension
  • Atomic content structures for reusability - transclusion
  • Dashboards for managing content and administration
  • Page Templating for custom page needs

Phase Two: Advanced Usage & Automation 🤖

  • MintyDocs and other plugins allowed us to start structuring content.
  • Implemented the Every Page is Page One (EPPO) model espoused by Mark Baker.
  • Switched to writing and best practices followed by cloud-based software.
  • Queryable interfaces for data that is always up-to-date with Cargo.
  • Implemented automation for a docs-as-code workflow.

Content as Data

Structured Authoring

We are not talking about DITA here.

  • A quasi-CMS layer atop Mediawiki for easy structured authoring.
  • Form-based authoring that adds a layer of metadata over content.
  • Support for multimedia content (images, animation, videos, and flowcharts).

Content Engineering

  • Develop customised templates for varying content types. (Page types like RN, Upgrade sections).
  • Define new content structures for resuable content (boilerplate text) or newer data models (Kafka events) or diagrams.

The Content-as-Data paradigm

  • Content can be converted into multiple data views like tooltips, FAQs, and embedded help.
  • Special Collector pages can be built automatically to act as landing pages or ‘content portals’.

Improved Automation

  • Automation enhancements for RNs and docs-as-code pipelines.
  • RSS Notifications for customers for Release Notes.
  • 🆕 AI-generated summaries for doc changes (won 🥉 in hackathon)

Phase Three: Implementing Content-as-Data 🆒

  • embraced the idea that content can be repurposed and made available in varying formats.
  • improved automation to reduce writer workload.
  • developed data structures that can accomodate different content needs.
  • build interesting ways to present content based on what users are looking for.
  • provide a better information experience.

Adopting a new platform need not be a source for worry.

Embracing change, making mistakes, having fun is part of any implementation.

Having a great team also helps. 😄



Happy to help/demo if you have any questions.