In a strange kind of tradition, we’re launching our new website for the freistilbox user documentation today. We’ve copied all articles over from our Zendesk Help Center (and will remove them there soon in order to avoid confusion). We’ve also used this opportunity to update and improve many of the articles and FAQ entries.

The motivation behind starting a new documentation website was threefold:

• Efficient content maintenance
• Fast and effective navigation
• Extensibility

Efficient content maintenance

As every developer knows, documentation is likely to be treated subordinate to implementation. Especially in a small team such as ours, there’s always work waiting either to improve existing or to build new feautures. In this environment, documenting how these features work or how to use them most effectively is often postponed to when customers actually ask about them in a support request. That’s not the quality of user experience we’re aiming at.

Additionally, maintaining content on a web-based system like the Zendesk Help Center is not the most efficient process when you’re used to writing in your finely optimised text editor of choice. That’s why we’ve been creating our documentation articles in Markdown text files stored in a Git repository for a long while now. On the one hand, this made the actual writing convenient and provided us with a change history for every article. On the other hand, publishing a new or modified article meant that we had to first convert it to HTML, then copy and paste it into the web form and then add additional metadata like tags/labels. The prospect of this tedious manual workflow didn’t exactly invite to make changes, so there always was the temptation of making changes directly on the website – and losing them again with the next update done correctly from the stale Git repository version.

Our new freistilbox documentation website is built with the Middleman static site generator. As until now, we write articles in Markdown and commit all changes to Git. But now, we can publish changes simply by making a git push to the central repository on Github. This push then triggers a CI process which runs a number of tests and (if they were successful), publishes the generated HTML files to Amazon S3 where the website lives.

Yes, we actually run tests on our documentation. At the moment, they only check that our source files adhere to a common Markdown style guide. In the future, there could also be tests for bad writing style such repeated words or overlong sentences.

Our new content publishing workflow will enable us to extend and improve our user documentation with the least effort.

Fast and effective navigation

We felt that using the Zendesk Help Center not only was less efficient for writing content, it also didn’t provide the best user experience to our customers. Finding the right article quickly is essential when you’ve got a question or issue and you’d like to check the available documentation before contacting technical support.

That’s why we’ve added a powerful search function to our new docs site that offers auto-completion and starts showing search results even while you’re typing. Behind the scenes, we’ll also get statistics that’ll help us improve our documentation based on actual search behaviour.

At the bottom of each page, you’ll also find a list of related articles that touch the same topics as the article you’re currently reading.

These improvements will help you find relevant content faster than before. We also hope they’ll reduce the number of support requests so that our engineers can spend their time on more demanding issues.

Extensibility

Search is just one example of how we wanted to make our documentation website as extensible as possible. This requires having full control over its inner workings, which we can’t get by using a third party solution.

Another small example is the link at the bottom of each page that actually allows editing the article in true open source fashion. Since we manage the content in an open repository on Github, everyone who’d like to make improvements to an article can fork the repository, make the necessary changes and send us a pull request. Simply click on the edit link and send us your suggestions!

Over the coming weeks, we’re going to add more features and, most importantly, more documentation that will help you using freistilbox better. If you have any feedback for us on the new website, write us an email or ping @freistilbox on Twitter!