Since 2008, Monetate has used Google Apps for Business company-wide to host our email and keep our calendars in sync.
Because Google Docs is included in that package, the engineering team decided it would be an easy place to put all of our internal documentation — “getting started” guides for new developers, walk-throughs of complicated tasks, documents describing code structure, and workflow, etc.
But as the engineering team has grown and the amount of documentation has increased, frustration with Google Docs has grown, too. The problem isn’t that Google Docs is a bad product — it’s actually a pretty good web-based alternative to traditional desktop apps like Microsoft Office. The problem is that we were trying to use Google Docs for something that it wasn’t designed to be.
Among our needs:
- The ability to create detailed technical documentation that includes lots of code snippets. It’s possible to paste code snippets into Google Docs and set them apart by giving them a different style, but if you’re looking for more advanced features such as syntax highlighting, line numbering, etc., you’re out of luck.
- The ability to easily link between documents, and sections of documents. It’s possible to do this in Google Docs, but it’s not dead simple, which is what we really want. (And if you click on a hyperlink, you then have to click a second time to actually go there, because the app doesn’t know based on that first click whether you’re trying to access the link or edit the link.)
- The ability to work with the data offline, in our own favorite text editors, without having to constantly download and upload copies.
- The ability to search the documentation quickly and easily. (This is something that Google Docs had in its favor.)
As it happens, at the same time the engineering team was looking for an alternative to Google Docs, we were also looking for ways to simplify our version control system. We had been using a system that relied on both Git and Subversion, which was needlessly complex.
For a variety of reasons, we decided to move our codebase to GitHub and eliminate our dependence on Subversion. And as luck would have it, GitHub offers a project wiki that seemed like it satisfied our needs.
Several months in, we’re pleased with the project wiki and have moved most of our documentation there, with plans to eventually move everything over.