Over the years, we've had several different flavors of Wikis. All of them failed to suit our needs at one point or another. When looking for a new solution we wanted a wiki that was easy to customize, non-bloated and had a good looking UI out of the box.
We found just that with Orientation. It's a small Rails app, highly customizable by anyone on our team. It comes with an interface that's easy to use and easy on the eyes. It also provides just enough features to be functional. We forked the Orientation's repository so that we can make changes as necessary. So far we've added image uploads and made a few other small adjustments.
Pages Contributions
Everyone should feel welcome and be able to contribute easily. For access right now we only require an authenticated Google apps email account from our organization domain. Once logged in you can browse and create new pages. The organizational system is fairly simple. We use tags to group related pages together and guides to provide a bit more structure to the documentation.
Guides
Guides are tables of contents for a subset of documents. A guide contains any number of links to wiki pages. We have a "New Employee" guide for newcomers and a product guide for each one of our applications.
Wiki Page on Writing Wiki Pages
This seems meta, but it helps people keep the wiki pages consistent and clean. A concise page provides guidance on naming conventions, tag usage and image upload info. We also provide a Markdown style guide on the sidebar of the edit page as a reminder of how to properly format pages.
Search
With around 200 pages and growing, we couldn't do without search. Though Orientation does ship with basic search, we'd like to improve it. Ideally the search results would pick out the portion of the page that matches the search query for easier results parsing.
Endorsements and Subscriptions
Both really neat features of Orientation, endorsements and subscriptions allow users to let the page author know they've found the page useful, as well as subscribe for page updates. Page authors receive an email when their pages are endorsed. Subscribers receive an email when the page is updated.
Rotten and Fresh
Users can mark a page as "Rotten" if it needs to be updated. This notifies the author that the page needs attention. Marking a page as "Fresh" essentially reverts the status. This feature also ships out of the box. Though it may not be earth shattering, it makes keeping docs up to date a tiny bit easier.
Orientation is one of the nicest, non-bloated wiki engines I've found. The ability to modify it as we see fit was one of the biggest sellers for us.
Hope you enjoyed this peek into how our wiki works. I expect to write a few more posts about our engineering culture and processes in the near future. Follow us @dox_engineering if you'd like to be notified about updates to this blog.
Thanks to Natasha Singh for reading drafts of this.
