New Home for Octopus Documentation

Published on: 2 Feb 2017 by: Paul Stovell

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.

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:

CloudShards shutting down

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:

Docs

Here's to remembering to take backups, even for hosted services!


Octopus Deploy is used by thousands of developers across the globe, from small companies to large enterprises. Find out if it meets your deployment automation needs by taking advantage of our free 30-day trial. You can spin up an instance with just a few clicks!