Today I setup a wiki for the all the common source code we created and/or use at b2cloud when developing apps, and I thought I would take you through the steps to creating one. Now the first things first, given that you are on a fairly typical Apache/PHP/MySQL setup (which most hosting providers are) then your first step will be going to MediaWiki and downloading the latest wiki software. Once you have downloaded this, extract it onto your computer (it comes it what is known as a tarball so on OSX this just means double clicking it, on Windows I would recommend downloading 7zip, and if you are on Linux you should not be wondering how to do this). Once extracting, go to your favourite FTP program and login to your server, once there find the subdomain you put it under, and locate the public_html folder. Everything in this folder will be public on the web, so by uploading the files you just extracted you will be uploading the core of the Wiki, if you wish to use a Wiki in conjunction with another service (such as WordPress) I would suggest making a new subdirectory or subdomain and putting everything in there. Now the waiting begins, let the FTP client slowly upload each file to the web server.
While thats going, I will explain what a wiki is, and why it is different to another kind of information medium (such as a blog). A wiki is, well exactly like wikipedia, it allows vast amounts of knowledge to be categorised, collected and added to by anyone part of the wiki, it is great for organising documentation on code for example. Let’s say that I made a change to a common coding object, I added in a method or a property, I can now push my changes to a git repository and write about the new method or property I added on the wiki, adding to the common knowledge. A wiki isn’t a way to the latest and greatest information onto people, although I have to admit WikiNews is kind of cool, it is simply a way to retain information. A blog would be more appropriate at pushing information, and that’s where software like WordPress comes in.
Now finally, the FTP has finished uploading the MediaWiki software to the server, go to where you put it (in my case wiki.b2cloud.com.au) and you will be greeted with a screen that tells you it needs to be setup. This is the web setup process where we tell MediaWiki how to interact with our MySQL database. We get to the screen called “Connect to database”, this is where we input the database username, host, password and a bunch of other things, unfortunately I can’t help with the database username and password but the host will be localhost in almost all cases (because MySQL will be running on the same server as your web server). Now instead of clicking “I’m bored, just continue” we are going to click the more options button.
On this page we are allowed to select the kind of user system we want. For b2cloud we are going to use Authorized editors only, because we can’t have just anyone coming here and changing our documentation. We are also going to select the CC license for our information so all information pulled from the wiki has to legally attributed to us. We are also going to change the logo URL to a b2cloud logo by uploading one to our site just next to the path they used to get the standard one. We will not do caching because we simply aren’t big enough to warrant it. If you are reading this blog and asking yourself “should I cache” then the chances are you shouldn’t.
Now this is a bit odd, it is saying it has generated a LocalSettings.php file that I need to download and upload myself using FTP, I would usually expect it to just write to a file itself but so be it, follow this instruction and the first hurdle is complete.
Now go to the wiki you have just setup, and you get a screen telling you it has been installed successfully! But wait… where’s our logo? It seems the installer has a bug, and doesn’t add it properly (let’s hope that is fixed before you read this). Some people don’t feel the need to add a logo, but I feel it’s important, and it shows that you care about the content inside enough to give it a branding. So we will simply go into our LocalSettings.php and add the following line (obviously replace the URL with your own URL and logo path):
$wgLogo = 'http://wiki.b2cloud.com.au/skins/common/images/b2cloud_logo.png';
And low and behold, success.
Here comes the bit where we have to put all our information on it, (well not all of it, we’ll be leaving out the source code for the vast majority of objects). The first step to this isn’t so much a programming or even an IT process, it’s a thought process. You have to make a list of your content and decide what the most logical way to categorise and organise it is. Since we are attempting to document our common objects my thinking was to write down the attributes all our source code might share:
– Whether it is a category or an object
– Whether it is used for user interface or functionality
– The general documentation on what it does
– The projects it has been used in
– The header (and depending on what it is, possibly the source)
– The changelog
– The resources
– Example usage
– Blog posts or any external links
Now from this, we can determine whether one of these attributes should determine its category or just a general attribute. Any time we have asked “Whether” we will that use as a category that we can group the entities in, the rest will be categories on the actual page for the entity (you’ll see what I am talking about in a second).
Let’s start putting information into the wiki, I will use an example of one of our classes UIStarView, it’s simply an object that allows us to render 5 stars in a UIView and select how many stars are selected. We need to create our UIStarView page, and to do that we will put the following URL into our browser: http://wiki.b2cloud.com.au/index.php/UIStarView
This brings us to a page telling us that UIStarView hasn’t been set up yet, and gives us a link to edit it. If we click this and write anything in that page that comes up and click save it automatically creates the page we need. So now that we have a page we need to create the attributes we discussed earlier. To do this we will enter the following into the edit page:
Testing UIStarView page = Documentation = The general documentation on what it does == Header == Header shall go here == Changelog == On the 5th of may I did change this == Resources == Just a list of file names == Examples == Here goes an example = Projects = A list of projects that we have done = External Links = The external links to a blog or whatever
Now if you press save, you will see this creates the attribute structure we are after, but what about the categories? Well to include them we add these in:
This tells the wiki software that have categories UIStarView into the UI category and the object category, this will make it easy to sort through source code later on. We will now add an image to the UIStarView page by putting in the following code at the top of the page:
Now if we go to the page, we can see that it has rendered something like this:
If we click on Uistarview.png in red it brings to a new page, but something horrible has happened. It won’t allow us to upload any files because uploading is disabled. To enable it load up LocalSettings.php and enter the following code into the bottom of it:
$wgEnableUploads = true;
Upload it again, reload the page and there is the file upload function waiting for us to go. Oh wait… now it’s telling us it doesn’t have permission to write to the upload directory, to fix this load up your FTP program and change the folders permissions to 777.
Now try it again, and you’ll see we have successfully uploaded an image. Go back to your original page and it will render it exactly where we expected it. Next we will be posting the Header of one of our source files to the page. Obviously we will want syntax highlighting, but first things first, we will need to add extensions as we find them. The first extension I added was WikiEditor, this creates a very user friendly WYSIWYG editor on the main pages, I just put this in for ease of use and I have faith that it will be continually updated given the amount of updates it has already had on it, remember to make it the default according to the instructions in the README. The second extension I will install is the SyntaxHighlight GeSHi, this allows us to do inline syntax highlighting, and is a requirement for automatic syntax highlighting on uploaded files, I also added the following code to LocalSettings.php to make the default language Objective C (because we are iOS developers mainly):
$wgSyntaxHighlightDefaultLang = "php";
But go to use it, and it renders strangely, it’s certainly not as clean as MediaWiki’s syntax highlighter, to change this go into the geshi.php file in the extension, and replace the following line with this one:
var $code_style = 'font-size: 12px; margin:0; padding: 10px 10px 10px 10px; background:none; vertical-align:top;';
This makes our code render much cleaner. Now we have gone through all the steps to set up a good online code documenter, good luck setting up yours.
Wrapping up, I’d say a wiki is actually quite hard to get your head around when compared to something like wordpress, the extensions are not as flexible and categorising content is lot more involved when regarding the syntax of the wiki which will be alien to many, even if you are a programmer. Having said that, since all wiki’s are basically open source, you can click edit on any page (even wikipedia) and see how they have set up their formatting categorisation and learn from example that way.