Use structued wiki markup to solve software documentation problems.

1. 1© 2016, Genesys Telecommunications Laboratories, Inc. All rights reserved.
MEDIAWIKI AS A
SOFTWARE
DOCUMENTATION CMS
Juan Lara <juan.lara@genesys.com>, @JRLtechwriting
Barry Grenon <barry.grenon@genesys.com>

2. 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. 3
STARTING POINT
• FrameMaker -> PDFs
• RoboHelp -> CHMs

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

5. 5
No budget?
Try open source

6. 6
PILOT PROJECT

7. 7
ENTER PONYDOCS
https://github.com/splunk/ponydocs
Support for:
• Products
• Manuals
• Table of Contents
• Versioning
• User Permissions

8. 8
GENESYS DOCUMENTATION

9. 9
PRODUCTS
[[Documentation:ListAllProducts]]

10. 10
MANUALS
[[Documentation:GCB:Manuals]]

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

12. 12
VERSIONING AND PERMISSIONS
[[Documentation:GCB:Versions]]

13. 13
NEXT EVOLUTION: STRUCTURED CONTENT

14. 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. 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. 16
CONFIGURATION OPTIONS

17. 17
SUPPORTED OPERATING ENVIRONMENT INFO

18. 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. 19
CARGO DESIGN PATTERN
Product
Managers
(Simple Data Input)
Engineers
(Complex Data Consumption)
Content Architecture Team

20. 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. 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)