User:Applicationswhisperer/how-to

Backstory/Phase I
In 2008, I was tasked with replacing an online help system (based on FrameMaker/RoboHelp) with a MediaWiki-based solution.

As with most projects, it took more time than anticipated, however, once we procured a hosted site and installed MediaWiki, I quickly became familiar with the basic editing and formatting syntax. Significant effort was spent reorganizing the existing help documents to fit an improved category scheme.

Finally, the help content was imported, and we launched the site. It was designed to behave as most context-sensitive help systems do: when the user clicks a Help link/icon in a web-based application, a new page opens with the relevant help content. Happy to say, this was successful and the MediaWiki-based help system went live in August 2008.

Phase II
Flush with our success, we set new goals:
 * build a single MediaWiki instance that supports two products, i.e. one wiki, two sites
 * single-source the articles (using conditional pages, text, images and navigation)

We found that with these MediaWiki features: Templates, Magic Words and ParserFunctions, we could achieve our goal of single-sourcing one wiki, supporting two sites. Here are the results of that effort:


 * Brand-A-Support-Site
 * Brand-B-Support-Site

How to Build an Online Help System using MediaWiki on a Hosted Site
How did we do it? Read on to learn more.

Key Resources and Advice
 * Resources:
 * Help:Contents
 * Wikipedia User Page Design Center
 * Manual:FAQ
 * MediaWiki announcements and site admin list
 * For Editing: FireFox and the It's All Text] FireFox extension, plus a Text editor (TextPad, Notepad, etc.)
 * Update on editors: Our users like [Extension:FCKeditor (Official)|FCKeditor Extension] because it offers a WYSIWIG interface


 * Install these apps:
 * 7-zip to unzip .tar.gz file to my PC
 * FileZilla for ftp access
 * Choose a 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) *Your hosting provider may offer to install MediaWiki (say yes)
 * 3) *Because mediawiki.org offers periodic upgrades, it's good practice to understand How to Install MediaWiki Upgrades
 * 4) Using FileZilla, create new folders (under /www, at the same level as /wiki):
 * /apples
 * /oranges
 * These folders are empty!!! However, they create these domain names: apples.foo.com and oranges.foo.com

Prep the Skin Files
Alternate advice to create new skin files: MediaWiki Look And Feel - Creating a Skin Based on MonoBook

This is what I did (via the PC, with the usual MS Windows commands):


 * {| 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> /skins/apples_MonoBook.php</tt>

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

Customize the Skins Files
With your text editor, customize the /skins/apples_MonoBook.php</tt> and /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 CaPitaLIzaTIon</tt>. Also, note that 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 {

Load the Skins Folder to the Hosted Site
Launch FileZilla and upload the following from your PC to the /skins</tt> folder on the server:

Folders: /skins/apples_monobook /skins/oranges_monobook

Files: /skins/apples_MonoBook.deps.php /skins/oranges_MonoBook.deps.php /skins/apples_MonoBook.php /skins/oranges_MonoBook.php

Create Logo and Favicon Files
These images/files create a graphic personality for your sites.


 * Create apples_logo.png</tt> file and place it in this folder: skins/common/images/</tt>
 * Create 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 (Apples Support or Oranges Support) based on the hostname (apples.foo.com or oranges.foo.com)
 * 2) Install any extensions after this code

$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'])==('oranges.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) ## I use a goofy logo and the monobook skin as the default ##    $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/sandboxlogo.png";

}

Extensions
We use these Extensions:
 * CategoryTree
 * ContactPage
 * TopTenPages
 * BreadCrumbs2
 * ParserFunctions
 * FCKeditor (Official)

In order for the site to work as promised, both the CategoryTree and ParserFunctions extensions must be installed.

Installing Extensions

Easy, once you know how. Generally, there are two steps to installing a MediaWiki Extensions:
 * 1) Download/save a <tt>.php</tt> file to the <tt>/extensions</tt> folder on your site; common situations:
 * 2) *If a download link is provided, download and save the file to your local drive (then unzip it if it's a compressed file/folder set)
 * 3) *If there is a big chunk of code displayed in the extensions page, copy and paste the code into a file (use a text editor), and save the file to your local drive (make sure to create the filename exactly as indicated)
 * After you have the file/folder set saved to your local drive, use FileZilla (ftp) to copy the files to the <tt>/extensions</tt> folder on your site
 * 1) Add the specified line of code to the end of the <tt>localsettings.php</tt> file; the exact code will be specified in the extensions page

Try it Out
Congratulations, you have achieved a one-wiki, two-sites state! Next steps:
 * 1) Open one of the sites
 * 2) Login
 * 3) Add some content and save the page
 * 4) Open the second site, navigate to the page (you might need to refresh the page) and see the copy in the new skin.
 * add several more test pages
 * add categories to a few pages
 * build out the conditional content

How to Install MediaWiki Upgrades
Before installing an upgrade, use FileZilla to backup the following to your local computer (because these files and folders will be overwritten during install/upgrade):
 * <tt>/skins</tt> folder
 * <tt>localsettings.php</tt> file
 * <tt>/images</tt> folder
 * <tt>.ico</tt> favicon images


 * The following is provided for future reference:
 * 1) Install MediaWiki according to the excellent instructions at MediaWiki Installation, as follows:
 * Download the latest copy of Mediawiki (filename: <tt>mediawiki-1.14.0.tar.gz</tt> in this example)
 * Extract the <tt>mediawiki-1.14.0.tar.gz</tt> 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 <tt>\mediawiki-1.14.0.tar</tt> folder and use 7-Zip again, to unzip the <tt>mediawiki-1.14.0.tar</tt> file
 * The result is a folder named: <tt>\mediawiki-1.14.0</tt>
 * Using FileZilla, copy the contents of the <tt>\mediawiki-1.14.0</tt> folder to the <tt>/wiki</tt> folder on the hosted site, i.e. <tt>/www/wiki</tt>
 * 1) In a browser window, navigate to your wiki site and install MediaWiki (this can take a while for first-timers; Great guide here: Siteground Knowledge Base)

Advanced MediaWiki Stuff for Conditional Content
Read about Templates, Magic Words and ParserFunctions - they are key to building a single-sourced site.

Parser Functions
If you're familiar with building conditional text in a publishing application, parser functions can do the same thing:
 * substitute page content, based on the site name
 * substitute brandname/feature/spec, using parser functions in a template
 * Change the Sidebar, based on site name

Substitute Page Content
Assuming the site is set up as defined previously, the following parser function example can be used to build conditional text; the sitename is used as the test criteria. With this concept, the conditional "chunks" can be images, images with text, text only, or whole pages -- you decide. Users of apples.foo.com will see apples-related content, and oranges.foo.com users will see oranges content.

In the following example, <tt> </tt>


 * ''In this example, a page is transcluded:

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

About Templates
Templates are powerful tools that support the single-source model.

A cautionary tale about templates
This guide is very useful and is a great starting point to understanding templates: Help:Template. I learned the hard way that templates defined in MediaWiki or Wikipedia must be added to your hosted instance. Doh!

Brand Template
Template:Brand plugs in the Apples or Oranges name whenever needed in an article. As a parser function, it compares the <tt>SITENAME</tt> with the first value <tt>Apples Support</tt>. If it's a match, the term <tt>Apples</tt> is used, otherwise, <tt>Oranges</tt>: <!--contents of Template:Brand>

Within pages, use Template:Brand as follows: 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...

When viewed in the Apples or Oranges skin, it's seamless. And, if the brand names change in the future, just change the template, and ALL instances will be updated with the new content when the page is viewed.

Using ParserFunctions with CategoryTree
This section describes how to have a custom sidebar in each site, based on the sitename.


 * 1) Install the CategoryTree extension
 * 2) Build the following template pages

Template:Tree chooses which category tree to display in the SideBar (based on Category Tree extension):

Template:Apples contains the Apples site SideBar:


 * 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

Template:Oranges contains the Oranges site SideBar:


 * 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

MediaWiki:Sidebar already exists. Replace the contents with:

With these Templates (Apples, Oranges and Tree), the sidebar will reflect the CategoryTree structure of each site. Because the concept of Categories is so powerful, the trees can be radically different, even though they are built from the same wiki database.

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 category 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

About Me
I have experience in product marketing, user training, technical communications and support desk operations:
 * I am comfortable diagnosing and solving most user-level PC/application problems
 * I know just enough about 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, not so much, but learning very quickly

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

Disclaimer

Everything described here was completed from my laptop, using only the resources listed ...no command-line processes were executed in the building of these sites.