Use that damn wiki

Posted on 1 Januar, 2011

First day in 2011 – the best time to tackle those new year’s resolutions. If you have been struggling with the overflow of information related to your iOS development, this post is for you.
For this iDevBlogADay post I want to illustrate how we at Spielhaus handle this overflow of information, or to put it simple – how we manage to stay on top of things with the proper tools.

The Problem

While writing code we focus on efficiency and are always on the lookout to improve and optimize stuff. There are however steps in the iOS development chain that need attention too – but unfortunately don’t get much love.
There is a wealth of knowledge that every iOS developer accumulates over time. The question is – where to store it? The brain is not the best storage device since it tends to forget things easily – especially those that are not needed frequently or are somewhat dull and tedious. I am not talking about basic stuff – that sticks. I mean those bits and pieces like libraries that one comes accross while searching to solve a problem, snippets of code that are related to a specific task, ideas for new apps but also marketing materials (where to book ads, list of review sites, reviewer assets, app store stats etc.). The problem gets worse since these bits are sometimes not related to each other and can not be categorized easily.

But what’s wrong with the status quo?

This is a valid question since managing information for the development of iOS apps is perfectly doable with low-tech tools. However the time that is saved when poping out another .txt file on the desktop to dump info, is wasted later when the information needs to be retreived. Plus how are we supposed to combine knowledge in an interesting new way if it is scattered all over the place?

Wiki

We decided to use a web based software to store all of our knowledge and supporting material. A wiki has the huge advantage that it is really easy to use and always available. This is especially important for a team that consists of more than one person (okay, our team is not that huge either – it’s just the two of us Trung and Stefan). Furthermore a wiki is a living thing with built-in memory because every page retains the versions it has gone through.
Apart from Wikipedia where I am just a user, I started to actively use wikis only a few years ago. Kudos to Martin Seibert from //SEIBERT/MEDIA (my former employer) who then forced us to use the internal wiki on a daily basis. This is how I came to appreciate its value.
At its core a wiki is a ‘simple’ system for editing and creating pages that may be structured hierarchically, categorized and linked to each other. Pages may contain text, images or have any number of attachments. There are plugins that extend its functionality to display charts, calenders, forms and so on. However the most important hurdle when using a system like this is its acceptance. It has to be used frequently to become useful. This might have been a source for nightmares for Trung for a long time while I constantly pesterd him to use that damn wiki. One trick is stop attaching files to emails but instead put them on the wiki and send the link to the wiki page. Over time our Spielhaus wiki has evolved into the central hub of everything we do to create apps.
Here are some screenshots of our Wiki. We use a custom theme called RefinedWiki but the first screenshot shows the default look.

We store there everything that is related to our business. For example every new app idea starts as a sub-page of the “Apps” page. From there other sub-pages emerge like – Concept, Mockups, Roadmap, App Store Descriptions (we keep a version of every App Store description to see if a new version had impact on sales). Later other sub-pages are created like Feature Requests, Reviews, Competitors and so on.

But we don’t stop there. Financial informations (how much and where we have spent and the income after Apple’s cut) are stored into an easy to read table. License codes, assets (images and sounds) are attaced to the ever growing “Assets” sub-page. Together with quotes for potential clients, market analysis, developer success stories, book summaries, meeting protocols – the wiki formes a huge conglomerate of valuable knowledge – much bigger of what Trung and I could ever memorize.

Confluence

I have chosen Confluence from Atlassian for a number of reasons. The most important one was its polish and ease of use as well as the flexibility it provides. There are many wiki packages out there – but to put it in Linux window manager terms – Confluence is the Gnome Desktop of them. I have chosen this metaphor for a reason. Many many years ago I have spent endless hours on my beloved Linux desktop, tirelessly tweaking every aspect of it. I wasn’t affraid to extend and recompile parts of (at that time Windowmaker, Fluxbox, Xfce) just to have everything setup perfectly. But while I grew up and free time became more and more scarce and precious, I started to use other window managers where I gave up some flexibility for the sake of simplicity and because much of the basic stuff worked out of the box. It is now the same thing with operating systems, code editors, wikis – there is always a trade-off between flexibility and maintainability.
With Confluence the tradeoff is very small. It is very flexible and at the same time has a ton of syntactical sugar (in terms of managing knowledge). These are the highlights that finally won me over:

Roll your own or hosted

Confluence is written in Java and runs under every major OS. Since I have a bad feeling of running a Windows server online, I was very glad to see strong support for Linux (together with tons of documentation (managed by Confluence of course)). There is also a hosted option if one doesn’t care where the own data is stored. Confluence is commercial software. It is not free. But at 10$ for the 10 user license it is more than a steal. I guess that’s what Atlassian thought too since the money for the ten user license goes completely to charity…

Made by developers for developers

Atlassian consists of a bunch of cool guys (and gals) who first created a tool for themselves to manage their internal knowledge. Eating your own dog food is the best way to ensure a great product.

It’s like driving a Jaguar

For a system that targets the dry topic of knowledge management, Confluence packs quite a number of bells and whistles. Keyboard shortcuts that allow mouse free editing, drag & drop attachments, dynamic content through macros, the WYSIWYG editor, a fine grained permission system are just the basics. This wiki was built for collaboration. There is a built-in blog, a twitter like “what are you doing” thingie, personal wiki spaces and one can build networks of people inside Confluence. Basically it is a complete intranet solution with a huge depth but a very light apperance. And since most features are optional, one can use whatever fits the purpose. But there is more. Pages can be rearranged via drag & drop, content can be tagged and displayed accordingly, OpenSocial gadgets can be incorporated, inline display of pdf documents and so on. There is so much more really useful stuff about it but I will refrain from praising every feature because I don’t want to appear like a Atlassian sales person. Besides I am not affiliated with them.
Here is the full feature list:

Here is a short usage video showing some features (make sure to watch it in full screen):
YouTube Preview Image

Conclusion

I hope I succeeded with my inception. There is a big potential for optimizing the workflow outside of Xcode that finally leads to an tangible advantage. The upfront overhead of setting things up pays big time after a short while. Knowledge is only valuable if you can make something useful out of it. The way knowledge is structured and stored is critical for the process of creatively combining and ultimately creating something new.

This concludes the actual post and I hope it was useful. Next time I will take a look at iOS related issue tracking with Jira.

Comments are closed.