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
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.
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!
11 Sep 2015
In the first week of August, we met for the latest installment of our company retreat named “freistil Days”. As a remote team, we come together every 5 months in order to strengthen our relationships and to do things we can’t do otherwise. On each retreat, we learn something that helps us improve the next one. In this post, I’ll explain what we learned this time.
The question of how long our retreat should be and how the schedule should look like is now pretty much settled. A whole week from Monday to Sunday has proven long enough to get a good bit of work done and short enough to limit the impact of our absence on the business and our families. We’ve arranged the schedule in a symmetrical way:
- Monday and Sunday are designated travel days.
- Midway through, Thursday is a good opportunity to do sight seeing so we get out and about a bit.
- This leaves two pairs of work days where we focus on projects.
Just like the previous times, we had prepared a schedule for these work days with time slots for project work, daily business, eating breaks and spare time. It hadn’t occurred to us until this time how hugely different this was from our normal year-round modus operandi. As a remote team, we trust that everyone knows their objectives and goals, and will work towards them. We don’t dictate when or how this work is to be done, though. This freedom creates a space for everyone to find their individual approach to working effectively. Halfway through these freistil Days, the Emperor’s Clothes question was finally spoken: “Why is our company retreat, of all things, the complete opposite?” We weren’t able to find a valid reason, so we decided to ditch the time slots, allowing everyone to decide individually when they’d work on freistilbox Solo, on support tickets or on other urgent business and when they’d rather lie down and read. From there, things got a lot more relaxed and (as expected) we still got a lot of work done.
Taking a break from work in the middle also does for a nice change. This time, we visited Hamburg’s Speicherstadt with the “Miniaturen Wunderland”, the world’s largest model railway. The amount of effort that went into building hundreds of square meters of model landscapes is amazing. And the control centre (see photo) was quite impressive, too. (Hey, we’re IT geeks.)
In advance of a retreat, we identify two or three projects on which we’d like to focus while we’re sitting around the same table. This time, we’ve decided to work on one customer-facing and one internal project.
The launch of our entry-level hosting plan freistilbox Solo has been delayed for months because we decided to base it on a new IT architecture that will also help us improve our existing enterprise hosting platform at a later time. freistil Days gave us the opportunity to focus on getting the new architecture further ahead and while it’s not finished, we’re much closer to a usable product now.
Behind the scenes we had noticed that our development workflows needed improvement. Now that there’s a whole team working on automating our IT infrastructure, the usual issues around collaboration, testing and releasing changes made us rethink how we do “infrastructure as code”. On a lovely Wednesday, walking along the green riverbanks of the Alster, we came up with a simple Continuous Deployment process that will give us everything we need with much less manual effort than before.
Spending a whole week together as a group certainly is a big difference to our normal team experience. All the unavoidable social interaction tends to draw a lot of energy, especially for introverts (which all of us seem to be to different extents). After a few days, our lunch conversations became less engaging and silent pauses got longer. Towards the end of the week, we all felt a bit exhausted.
So it was a good decision to get rid of the rigid schedule because this will allow us in the future to take time off the group whenever we like, whenever we feel it’s necessary.
On the plus side, we got a better understanding for each other and more clarity about our strengths and weaknesses.
Third time’s the charm! Our freistil Days in Hamburg advanced us as a team and as a company. We deepened our relationships and made progress on our products and internal processes. And most importantly, we had a lot of fun!
If you’d like to see for yourself what freistil Days (and the rest of the freistil year) are like, get in touch!
21 Aug 2015
Sometimes you need to jump back in your git history to an old state. Most of
the times you already published your commits to other remotes so a
--hard $OLD_COMMIT is not a solution.
This is where
git revert comes in
If you want to jump back to a specific commit id
48b616601cab02df84297dcf7246d17072ac32fb all you have to do is
git revert -n 48b61660..HEAD
Now check everything and create a new commit that reverts everything from the old state to the current.
13 Jul 2015
When our monitoring alerts us of a server because of a full root file system,
determining the cause is a bit harder than with other file systems because many
/ are actually mount points of separate file systems.
There is an easy way to isolate the root file system content, though: mounting it a second time elsewhere.
A normal mount will fail:
mount: /dev/mapper/vg0-root already mounted or /mnt busy mount: according to mtab, /dev/mapper/vg0-root is mounted on /
But a bind mount does the trick:
$ mount --bind / /mnt $ du -sh /mnt/*
12 Jul 2015
The result of their work is, and I’m really not exaggerating, awesome. Not only did Palasthotel give the website a fresh design, they also did great development work behind the scenes:
- 130.000 articles needed to be migrated from Escenic to WordPress. Inspired by Drupal’s “Migrate” module, Palasthotel developed a WordPress migration framework which they’re going to make Open Source.
- The site uses 79 plugins, 69 of which were developed in-house.
- Homepage and landing pages were built with PalastHotel’s plugin Grid.
- Not only is the website responsive but it also uses “responsive images” technology that loads images only on demand and in the right resolution.
- For maximum search speed, Palasthotel developed their own interface plugin for Apache Solr (soon to be published, too).
- In order to simplify collaboration between three editorial teams, Palasthotel built a solution for sharing image galleries between separate WordPress setups.
- The site uses 8 custom post types for artists, concerts, festivals etc. For connecting these post types, Palasthotel developed a “Post Relationships” plugin (which they’re going to publish as well).
- Their new “Postqueue” plugin allows creating hand-picked content lists, just like the “Nodequeue” module in Drupal.
- And as if this list wasn’t impressive enough already, Palasthotel built and integrated Octavius into the site, their own real-time click tracking service.
Shortly after the relaunch, Ben teamed up with our Chief Uptime Officer Markus for a session at WordCamp Cologne where they presented how our teams cooperate to run High Load Websites reliably, with the Rolling Stone Magazine being only one example.
Congratulations to our friends at Palasthotel for a job well done!
26 Jun 2015
In Drupal 7, database logging via the “dblog” module is enabled by default. On high-traffic websites, this can become a problem. When Drupal generates lots of log entries, they can cause significant write load on the database and fill it up quickly. We’ve seen many database backups take longer than an hour because the “watchdog” table was multiple Gigabytes big, and more than one website database bog down under log write load.
The best solution is of course to to fix all PHP notices and warnings to reduce logging overhead. But you’ll still want to have a way of preserving important events in order to analyse them if the need arises. With the “syslog” module, there’s a better alternative to “dblog” and we’ve recently added syslog support to freistilbox. All log entries will simply be written to a log file in your website’s “logs” directory.
If you use our pre-built configuration snippets (and you should), all you need to do is to enable the “syslog” module. Our configuration snippet already comes with all the right module settings. And don’t forget to disable the “dblog” module!
23 Jun 2015
A few days ago, a new SSL vulnerability called “Logjam” was published. The attack exploits weak “Diffie-Hellman” (DH) parameters in incorrectly configured SSL/TLS servers.
We decrypt incoming SSL traffic right on our Edge Routers in order to enable content caching for both plain-text and encrypted web requests. Since we follow best practices, we don’t use any of the vulnerable cryptography. No changes in our Edge Routers were necessary to mitigate LogJam.
In order to deliver the best SSL processing performance possible, our Edge Routers prefer key exchanges based on “Elliptic Curve” cryptography, thus avoiding problems with DH altogether.
We are proud that the SSL configuration of our Edge Routers is rated “A+” by SSL Labs, and happy to give you peace of mind about the security of your website traffic.
28 May 2015
Bring together Drupal developers, themers, end users and those interested in learning more about Drupal — that’s the mission of the Drupal Open Days, the biggest DrupalCamp in Ireland. It’s happening again, and we’d like you to be there, too!
On May 22 and 23, we’ll have two days of talks, sessions and collaborative discussions about Drupal. Like last year, the main event will be at the Guinness Enterprise Centre and we’ve reserved space at nearby pubs to continue our conversations in the evenings after the sessions.
The Open Days team is doing amazing work behind the scenes preparing everything. Please help us spread the word so that lots of people interested in Drupal will make this event a great success!
We’ve gathered a bunch of brilliant speakers, first of all Emma Jane Westby with “Managing Projects the Drupal Way”. Peter Sherrard, FAI Communications Director, and Daniel Walsh will present “The Football Association of Ireland’s Drupal & UEFA API Experience”. It’ll be two days packed with information about how to use Drupal successfully!
As a company based in Ireland and, more importantly, a part of the Irish Drupal community, freistil IT is happy to support Drupal Open Days as a Gold Sponsor. I’ll be around on both days (and nights), so don’t hesitate to chat me up if you’re interested in having your Drupal website(s) run by experts.
It’s important that we demonstrate that Drupal has critical mass in Ireland. So again, please tell your friends, colleagues and customers to join you at Drupal Open Days.
Sign up now and be a part of the greatest Drupal meetup in Ireland!
06 May 2015