How did a single team’s documentation wiki grow into an essential piece of the organization? By carefully crafting a reliable and flexible tool, everyone learned the benefits of shared knowledge. While our specific situation refers to a MediaWiki implementation within our organization in the year 2011, the concepts outlined could likely extend to any collaboration tool now and in the future.
A Netted Garden
Before the adoption of the current organization wiki, a previous iteration of a web-based wiki existed for a single team. The old wiki was riddled with access control lists and restrictions. To even start viewing it, you needed to be manually added as a user. Hardly simple or friendly.
When the new system was pitched, it was decreed that the information would be opened organization wide. No restrictions anywhere. Why hide system administration details from the developers or vice versa? Even if a member decided to vandalize other groups documentation (purposefully or accidentally), all changes are audited along with built-in versioning for easy rollbacks.
We offered open guidelines for creating useful and consistent information architecture, but did not slap on restrictions except for obvious cases (not posting passwords, etc.) for security. The system now thrives on this flexibility. All members of the organization have become content curators. Iteratively, the service becomes more valuable to everyone.
How Did It Grow?
Easier to say than achieve, we gathered people on a common language built around simple, easy to access information. In our case, a web based wiki provides a common denominator of no proprietary software restrictions and global access. When a product can stay out of the way to let people get done what they need to get done (in this case documentation) it becomes synonymous with the workflow.
We created a community where it allowed the collaboration tool to become popular, naturally. Strong-handedly forcing adoption of tools leads to skeptics and outliers. If it’s worth its weight to the organization, they will flock. Flock they did. You know you’ve made it when your product becomes subconscious to those involved, like how many people will go straight to specific friends or websites to find what they need without giving a second thought.
Blurring the Lines
Allowing the wiki to grow naturally gave credence to the idea that centralized, yet open documentation is useful to the organization. With more eyes on the documentation, now anyone can see how other groups operate and improve any service by offering suggestions or prototyping. We’ve seen many cases where developers from one group will comment and help others. Physical location no longer applies. This leads to blurring the notion of organizational silos.
Creating Value for Everyone
It was very simple just to offer the service internally to just our department as a single instance, but why stop there? We opted for a modular design where new wikis (for other departments or very specific needs such as a wiki for a class) can be added simply. This modular design benefits with automated maintenance tools (backups, upgrades, etc.) and shared blocks of configuration (authentication, extensions, etc.) developed to simplify and solidify the environment’s operation.
Stand By Your Product and Depend On It
Our wiki has become a central documentation tool for everything from information about applications and services to disaster planning. Now think about that last one for a second. When disaster strikes and knocks out the wiki, how will everyone get their documents? It is about preparation for all scenarios.
- A localized, server confined disaster where the system crashes or data on it becomes corrupt
- A localized, external disaster where there are issues with the hosts, storage, network, cooling, or power within a rack or the whole data center
- A regional, external disaster affecting multiple (or maybe all local) sites
Let us get technical with our MediaWiki implementation and disaster mitigation. While the standard product does not offer any built-in options for high availability out of the box, we architected multiple recovery schemes for the above situations.
- Standard daily off-server system backups to disk and tape
- Application layer backups (MediaWiki XML)
- Database layer backups (MySQL dumps)
- Database layer replication (MySQL)
- File layer replication (rsync)
- Message with recovery instructions for administrators logging into the system directly
Most importantly, the powerful combination of replications allows us to simultaneously run warm spare server(s) in other data centers on or offsite for a really quick return to operation time. The last item is for the panic moment of failing over the system if necessary (to enable write access, read access is available on standby systems at all times). Having the instructions outlined provides a sense of relief in the face of a larger crisis.
Parting Thoughts
No product should be developed by one person or small, exclusive group. Customers can be your best developers, even if they are not touching the actual code or configuration. Listen. React. Be proactive for demands they don’t know they have yet. Grab enthusiasts and hack away at new models. For experimenting with the new, release early in development and iterate away. Sometimes your final product will look nothing like it started. This is always for the better.
The continuing success of our wiki environment is because of the collaborative nature of the tool itself. When colleagues are discussing the documentation available on there, it has migrated from “your” information to “our” information. There is immense power in that statement. Empowered people will add their creative and experiential input. We all win.
