1© 2016, Genesys Telecommunications Laboratories, Inc. All rights reserved.

MEDIAWIKI AS A SOFTWARE DOCUMENTATION CMS

Juan Lara <juan.lara@genesys.com>, @JRLtechwritingBarry Grenon <barry.grenon@genesys.com>

2

WHO IS GENESYS?

Biggest software company in the valley that no one has ever heard of.*

*Thing Genesys people say at cocktail parties

3

STARTING POINT• FrameMaker -> PDFs• RoboHelp -> CHMs

4

STARTING POINT• FrameMaker -> PDFs -> Updated only twice a year • RoboHelp -> CHMs -> Must be ready one month before software release

5

No budget? Try open source

6

PILOT PROJECT

7

ENTER PONYDOCShttps://github.com/splunk/ponydocs

Support for:

• Products• Manuals• Table of Contents• Versioning• User Permissions

8

GENESYS DOCUMENTATION

9

PRODUCTS

[[Documentation:ListAllProducts]]

10

MANUALS

[[Documentation:GCB:Manuals]]

11

TABLE OF CONTENTS[[Documentation:GCB:DeploymentTOC8.5.0]]

12

VERSIONING AND PERMISSIONS

[[Documentation:GCB:Versions]]

13

NEXT EVOLUTION: STRUCTURED CONTENT

14

STRUCTURED CONTENT - SIMPLE◉ First, simplest structured content project (DPL): Integrated Glossary

Glossary Front page Individual Glossary Term page

Glossary popup in docs page

15

STRUCTURED CONTENT – GETTING COMPLICATED

◉ Genesys products are highly customizable – > 10 000 configuration options in Genesys – stored, with descriptions, in XML files (10 756, according to Cargo)

◉ Process:● Script writes content from XML files to discrete wiki pages using MW API.● Discrete pages live in a dedicated, internal-only namespace.● Content saved in structured template format.● Content is pulled into public pages in various ways: portal lists, query form, popups

embedded in regular articles

16

CONFIGURATION OPTIONS

17

SUPPORTED OPERATING ENVIRONMENT INFO

18

CARGO DESIGN PATTERN

◉ Design content structure. Build cargo database.◉ Design an input interface with PageForms.◉ Create templates and queries for data consumption (as many flavors as

you like).

19

CARGO DESIGN PATTERN

Product Managers

(Simple Data Input)

Engineers(Complex Data Consumption)

Content Architecture Team

20

WHERE WE WANT TO GO◉ Refactor Ponydocs to use Cargo.◉ Create strict templates & forms for page types.◉ Gather controlled metadata whenever a page is created.◉ Leverage metadata for rich subject affinity linking.

21

WHERE WE WANT TO GO◉ Refactor Ponydocs to use Cargo.◉ Create strict templates & forms for page types.◉ Gather controlled metadata whenever a page is created.◉ Leverage metadata for rich subject affinity linking.

+ Ponydocs + -> EPPO CMS(Every Page is Page One)