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
Products
Source View
Rendered View
Manuals
Source View
Rendered View
Table of Contents
Source View
Rendered View
Versioning
Source View
Rendered View
Access Control
Improvements to Mediawiki
Automation for Release Notes
- built a tool to export release note content out from JIRA to Mediawiki.
- open sourced the JIRA plugin
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
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
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.
Search enhancements
- A custom-built search engine that provides faceted search across two Mediawiki platforms (PonyDocs and MintyDocs).
- Writers could update the search index (if needed) immediately or restrict pages from being indexed.
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. 😄
References
MediaWiki extensions:
- Cargo, Page Forms, Visual Editor, Tweeki skin
- PonyDocs - considered abandoned 😞
- MintyDocs 🆕 specific to our needs
Genesys Documentation
- https://docs.genesys.com uses PonyDocs
- https://all.docs.genesys.com uses MintyDocs
🙏🏾
Happy to help/demo if you have any questions.