User:Applicationswhisperer

Last summer, we moved an existing online help system to MediaWiki, replacing a FrameMaker-to-RoboHelp solution that didn't work as online help for the PaaS services we offered. Result: LongJump Support

MediaWiki Project
Goal:
 * build one wiki supporting at two products (similar services, different branding)
 * single source the articles (i.e. write once, use many; conditional text/images)

Outcome:
 * Achieved the goals using MediaWiki with templates, inclusions and parser functions

Key Resources: Use these resources, they are your friends when you're a newbie:
 * Manual:FAQ
 * MediaWiki announcements and site admin list
 * Since we do our wiki editing live, this combo saved the day: Text editor (TextPad, etc.), FireFox and the It's All Text] FireFox extension
 * Install these apps:
 * 7-zip to unzip .tar.gz file to my PC
 * FileZilla for ftp access
 * Hosting provider; We used Siteground; They have helpful MediaWiki advice

Setup a Hosted Site and Domain Names

 * 1) Acquire a site; For the purposes of this article, my site name is: www.foo.com
 * 2) Install MediaWiki according to the excellent instructions at MediaWiki, as follows:
 * Download the latest copy of Mediawiki (filename: mediawiki-1.14.0.tar.gz)
 * Extract the mediawiki-1.14.0.tar.gz file to a folder on your PC; To do this, hover the cursor over the file, right-click and select 7-Zip, choose Extract Files; Click [OK] (trust the defaults)
 * Open the \mediawiki-1.14.0.tar folder and use 7-Zip again, to unzip the mediawiki-1.14.0.tar file
 * The result is a folder named: \mediawiki-1.14.0
 * Using FileZilla, copy the contents of the \mediawiki-1.14.0 folder to the /wiki</tt> folder on the hosted site, i.e. /www/wiki</tt>
 * 1) Using FileZilla, create new folders (under /www</tt>, at the same level as /wiki</tt>):
 * /apples</tt>
 * /oranges</tt>
 * These folders are empty!!! However, they create these domain names: apples.foo.com</tt> and oranges.foo.com</tt>

Prep the Skin Files
The file edits in this section were created using FileZilla, modified to use TextPad as the default editor.

Open FileZilla and add the following folder/files in the /skins</tt> folder
 * {| border="1" cellpadding="5" cellspacing="0"
 * {| border="1" cellpadding="5" cellspacing="0"

/skins/monobook</tt> /skins/apples_monobook</tt>
 * Copy this...
 * ...and Paste as:

/skins/oranges_monobook</tt> /skins/MonoBook.deps.php</tt> /skins/apples_MonoBook.deps.php</tt>

/skins/oranges_MonoBook.deps.php</tt> /skins/MonoBook.php</tt> <tt>/skins/apples_MonoBook.php</tt>

<tt>/skins/oranges_MonoBook.php</tt>
 * }

Customize the Skins Files
With your handy-dandy text editor, customize the <tt>/skins/apples_MonoBook.php</tt> and <tt>/skins/oranges_MonoBook.php</tt> files with the following code; This code is is located near the beginning of the file; The following code is (obviously) a sample for Apples. Build the Apples files and do it again for Oranges. Pay attention to <tt>CaPitaLIzaTIon</tt>. Also, there are five places in this code that need to be tweaked:

/** * Inherit main code from SkinTemplate, set the CSS and template filter. * @todo document * @ingroup Skins */ class SkinApples_MonoBook extends SkinTemplate { /** Using monobook. */	function initPage( &$out ) { SkinTemplate::initPage( $out ); $this->skinname = 'apples_monobook'; $this->stylename = 'apples_monobook'; $this->template = 'Apples_MonoBookTemplate'; # Bug 14520: skins that just include this file shouldn't load nonexis- # tent CSS fix files. $this->cssfiles = array( 'IE', 'IE50', 'IE55', 'IE60', 'IE70', 'rtl' ); } }

/** * @todo document * @ingroup Skins */ class Apples_MonoBookTemplate extends QuickTemplate {

Create Logo and Favicon Files

 * Create <tt>apples_logo.png</tt> file and place it in this folder: <tt>skins/common/images/</tt>
 * Create <tt>oranges_logo.png</tt> file and place it in this folder: <tt>skins/common/images/</tt>
 * Create <tt>apples_favicon.ico</tt> file and place it in this folder: <tt>/www/wiki/</tt> root (i.e. <tt>$wgScriptPath</tt> in this example)
 * Create <tt>oranges_favicon.ico</tt> file and place it in this folder: <tt>/www/wiki/</tt> root (i.e. <tt>$wgScriptPath</tt> in this example)

Customize <tt>localsettings.php</tt>

 * 1) In <tt>localsettings.php</tt> add this block of code at the end; It will set the sitename, based on hostname
 * 2) Install any other extensions, also at the end;

$wgEnableParserCache = false; $wgCachePages = false;
 * 1) added to resolve Apples vs Oranges parserfunction issues on the home page
 * 1) added to resolve Apples vs Oranges parserfunction issues on the home page

if(($_SERVER['HTTP_HOST'])==('apples.foo.com')) {   $wgSitename = 'Apples Support'; $wgLocalInterwiki  = $wgSitename; ## Default skin for Apples
 * 1) Choose the wiki support site, based on the host name (apples.foo.com or oranges.foo.com)
 * 1) Choose the wiki support site, based on the host name (apples.foo.com or oranges.foo.com)

$wgDefaultSkin = 'applesmonobook'; $wgLogo = "skins/common/images/apples_logo.png";

$wgFavicon = "$wgScriptPath/apples_favicon.ico";

}

else if(($_SERVER['HTTP_HOST'])==('lj.foo.com')) {   $wgSitename = 'Oranges Support'; $wgLocalInterwiki  = $wgSitename; ## Default skin for Oranges

$wgDefaultSkin = 'orangesmonobook'; $wgLogo = "skins/common/images/oranges_logo.png";

$wgFavicon = "$wgScriptPath/oranges_favicon.ico";

} else {   ## For convenience, all edits are conducted from (wiki.foo.com) ## (With my avatar as the logo, it makes me happy,   ##  and whatever makes me happy helps me be more effective) $wgSitename = 'SandBox Support Wiki'; $wgLocalInterwiki  = $wgSitename; ## Default skin: you can change the default skin. Use the internal symbolic ## names, ie 'standard', 'nostalgia', 'cologneblue', 'monobook':

$wgDefaultSkin = 'monobook'; $wgLogo = "skins/common/images/sandbox.png";

}

Going forward, add any MediaWiki Extensions at the end of the file, after this section of code.

Parser Functions are Your Friend
With the site setup as outlined here, the following parser function can be used to substitute one page for another, depending on the name of the site. In the following example, <tt></tt>

Extensions We Use

 * ContactPage
 * TopTenPages
 * BreadCrumbs2
 * ParserFunctions

CSS for Dummies
Get friendly with your local web developer. Provide a copy of the monobook folder and ask for whatever css cusomizations strike your fancy. Don't go wild, tho, because making major changes will break some extensions. My advice is to stay with basic fonts and colors, logos and favicons. We went very zen (LongJump Support).

Now for the Magic
Build the following template pages.

Tree chooses which tree to display in the SideBar (based on Category Tree extension).

Template:Tree

Apples is the contents of the Apples site SideBar: Template:Apples
 * navigation
 * mainpage|Main Page
 * topic-1|Topic 1
 * topic-2|Topic 2
 * topic-n|Topic N
 * Category:Glossary|Glossary
 * topic-n|Topic N
 * Category:Glossary|Glossary
 * Category:Glossary|Glossary

Oranges contains the Oranges site SideBar: Template:Oranges
 * navigation
 * mainpage|Main Page
 * different-topic-1|Topic 1
 * different-topic-2|Topic 2
 * different-topic-n|Topic N
 * different-topic-n|Topic N
 * different-topic-n|Topic N
 * different-topic-n|Topic N

In MediaWiki:Sidebar, add:

Brand template plugs in the Apples or Oranges name whenever needed in an article. Where behavior is the same and only the name is different, use this:

Template:Brand <!--contents of Template:Brand>

Within pages, use Template:Brand This is an article about the industrial-strength power of bla-de-bla...

Which results in an article containing one of the following, depending on the URL they visited:


 * This is an article about the Apples industrial-strength power of bla-de-bla...
 * This is an article about the Oranges industrial-strength power of bla-de-bla...

About Me
I have experience in marketing, training, technical communications and support desk operations:
 * Technology is my friend, and I am comfortable handling most L1/L2 PC problems
 * I know just enough DOS/UNIX commands to be dangerous
 * Until now, I have used other tools to create user documentation (FrameMaker, RoboHelp, DreamWeaver, Acrobat), plus some of the early programming languages...so, Fortran, Cobol and BASIC, yes ...PHP and mySQL, no, but learning very quickly.

Currently, I'm a technical writer in the SF Bay area. Contact me at eyodertw at yahoo dot com.

Project History

 * When I started this project, the RoboHelp content was six months out of date
 * First milestone: Pull RoboHelp articles into MediaWiki
 * I tried the robo2wiki extension, but the RH site had many pop-ups and fold-out content, so the result in MW was very ugly, with jillions of tiny articles from all the pop-ups, plus similar-but-different redundant content
 * The best result was exporting RH to PDF, then copying and pasting from PDF into MW...cumbersome, but it allowed me to become familiar with the materials, and identify needed art and topics
 * The result was that I could consolidate redundant content, and build a single MW page; These pages could be cross-referenced from an article, or used as a template for inclusion into a larger overview article


 * In the following months, I added extensions and learned the subtleties of templates and parser functions.