We've moved our documentation to octopus.com/docs, and the source for the docs is in Markdown and hosted in GitHub.
Since 2012, we've hosted the product documentation for Octopus Deploy in Atlassian Confluence. Atlassian provide a cloud-hosted version of Confluence, but for reasons only they can explain, they don't support CNAME's, something that's important to us. This left us with two choices - we could either host it ourselves, or find someone else to host it. We chose a company called QueryFoundry, and they'd hosted Confluence for us pretty reliably for about the last 3 years.
On 17th of January, we awoke to find our documentation was offline. So was QueryFoundry's site. We waited, assuming they'd be back online soon enough. 24 hours later, they were still offline, and they'd only provided a couple of status updates by then - things were looking bad.
DFW Update 1: Switch fabric module failure in one of our core routers is responsible for the outage. We're working to replace w/ vendor.
— Query Foundry (@queryfoundry) January 17, 2017
Unfortunately for us, we didn't have any recent backups of our documentation. We quickly put up a page to say our documentation was unavailable, then started scouring Google's cache and Archive.org to find copies of the pages. At this stage we assumed our documentation was never coming back!
About 48 hours later, QueryFoundry recovered and our Confluence server was back up. We were able to export our documentation, catch our breaths, tell ourselves off for not having recent backups, then sit down and come up with a plan.
We had a few options:
- We could stick with QueryFoundry - after all, these things happen. But I was disappointed with how few status updates they'd made during the outage.
- We could find someone else to host Confluence
- We could look for something else
For API or library documentation, there are some great hosting options - readme.io being one of my favorites.
Eventually, inspired by our friends at Particular, we decided to convert all of our docs to Markdown, and put them in a GitHub repository - it's nice to use GitHub or a text editor locally to edit the documentation.
We'd originally planned to use a static site generator over the markdown, but we wanted it to integrate with the rest of our website search/sitemap files, and to host the documentation at octopus.com/docs. So, we built a tool to sync them into the home-built CMS that runs this site, using Markdig to do the conversion.
Anyway, it's good that we started the migration as soon as we did... about a week after the initial outage, we got this sad email from CloudShards:
It's taken about a week to go from the Confluence exports to hosting on our own site, and we still have to go through a few pages to manually fix them up, but I'm pretty happy with the end result:
Here's to remembering to take backups, even for hosted services!
