You might have noticed that we’ve spruced ourselves up lately. But as well as working on shiny new outsides, we also wanted to spend some time improving the nuts and bolts of the Tyk product itself.
This came in the form of a full review of our documentation, both from a technical accuracy viewpoint (very important), and from a functionality viewpoint (also important). This means making it easier to navigate our tutorials and to search for content quickly and easily. On top of this, we’re committed to the Open Source philosophy, and want to apply this approach to our documentation as well.
What are Open Source docs?
Put simply, it’s treating our Open Source Tyk documentation in the same way as our Open Source Tyk software. Our docs are available for anyone to clone and contribute to, via our Tyk documentation GitHub repo.
Why have we done it?
A few reasons!
We want to make our documentation available to our customers in the same way as our code. We know our community is a clever bunch; if you’ve done something you feel the Tyk Community would benefit from, we want to encourage you to contribute. This includes additions, updates or corrections to our documentation using our Tyk GitHub repo.
Plus, as the API world is very open source friendly, open sourcing our customer facing docs seemed the natural and right thing to do. As well as being part of our own Open Source business ethos, Tyk are proud members of the Open API Initiative, an organisation that is committed to “creating an open description format for API services that is vendor neutral, portable and open”.
Documentation is often a bit of an afterthought; we’ve changed that. We were already aware, from feedback from the Tyk community, that the existing Tyk tutorial documentation need some work to make it more “user friendly”. This was especially true for the documentation when viewed on mobile devices.
As part of the process we’ve sped up how we add new content ourselves, as team Tyk. We have big plans for the kind of content we provide to help our customers get the best out of Tyk; all these improvements will provide a positive foundation towards that.
How have we done it?
There is a growing trend towards treating documentation content in the same way as code: using static web site generators and the content written in Markdown.
We used Hugo as the framework for our docs and created a Tyk theme to keep it consistent with the rest of the new website branding. We then converted our existing docs into Markdown and added it to Hugo.
You can see the end product at our Tyk documentation Github repo. We’ve also written a separate and more detailed post on how we used Hugo, Algolia, Github, and Buddy to Open Source our docs.
Additional improvements
As well as open sourcing our docs, we’ve also improved the following on our Tyk Getting Started documentation.
- Search. We’ve incorporated Algolia’s search functionality which has vastly improved the docs search.
- Restructuring. We are busily restructuring the docs to make them easier to navigate and to read
- Filling the gaps. Our new docs strategy is making it quicker to add more information as we need to.
Have a play around with our new Open Source Documentation. Read it, disagree with it, submit changes, and please, give us feedback.
To find out more about this process, read our blog on how we used Open Source tools to Open Source our own documentation.
