Having explained why we have open sourced our documentation, we wanted to let you know a bit more about how we did it.
Our docs were originally created within our WordPress powered website. This included the use of two plugins to get the content to display using a Table of Contents. It was a bit clunky, the search didn’t work too well (that’s being polite), and the Table of Contents wasn’t easy to navigate or very mobile friendly. This had to change.
Hugo is one of a number of static website generators that have become very popular in the last couple of years. In many ways this is a sort of ‘back to the future’ way to do web design. No databases and creating the site pages and or posts using Markdown formatted text files that are then built into your site. Sites can be viewed locally before “going live”, and you can use themes to give the site its look and feel.
Just like WordPress, Hugo and the other static website generators were originally designed around use for creating blogs, but have been adopted to create sites with a whole variety of content, including documentation.
Hugo, like Tyk, is open source and written in Go, so it was a no-brainer to use it given the extensive Go expertise we have in-house. It can be installed on Mac, Linux and Windows, which means it is flexible for anyone to contribute to. We were able to develop our own theme easily, which meant it could adopt our shiny new look.
We are already looking at other functionality that Hugo can give us, such as the use of shortcodes to improve on what formatting is supported in Markdown, as well as developing a Taxonomy, which gives us content classification for our content.
Seek and you will find
The next piece of the puzzle to solve was to implement a decent search for the docs. We looked at a few options, but settled for the Community edition of Algolia. We built an initial index, submit it to Algolia and now we update it via their API as necessary.
Version Control and Reviewing
Making our docs open sourced via GitHub also means we get version control and review capabilities. Usually you pay serious money for Documentation Content Management Systems that offer this kind of functionality. With GitHub, we get it for free.
We use Buddy for the final piece of the Hugo docs site generation. This picks up any commits to our master branch, builds the HTML and associated site files, and then deploys them to our development site. Then we follow our usual deployment process to get it to live.
So now you know how we’ve done it, why not have a play around with our new Open Source Documentation? Read it, disagree with it, submit changes, pull it apart if necessary – we’d love to hear what you think.