After experimenting with Jekyll as a documentation platform for the past several months, I decided to migrate my blog from WordPress to Jekyll.
Although I think WordPress is a nearly perfect blogging platform, and I have extensive knowledge about building sites in WordPress, I still made the switch.
Here are some reasons why I switched:
My main reason for switching probably differs from the most common reasons people switch from WordPress to Jekyll. I think that the publishing platforms we use to create technical documentation shouldn’t be different from the publishing platforms we use to publish to the web.
Throughout my career I’ve been using MadCap Flare or MediaWiki or OxygenXML or some other tech comm tool during the day, and then switched to using WordPress to blog in the evenings. Then it’s back to tech comm tools in the morning.
Well, I’m tired of this split paradigm when it comes to publishing. Why should web publishing tools be any different from tech comm publishing tools?
Although WordPress offers 30,000 plugins, allowing you to build nearly anything, there’s a hidden cost to each plugin. If you add more than a dozen plugins on your site, it slows down considerably.
In the past, I’ve tried integrating BuddyPress (WordPress’ social network platform) to build more of a community. No matter how many tweaks I made to speed up my site, the load time was around 4-5 seconds. I finally gave up on the community idea.
About a year ago, I made a relentless effort to get my site’s speed down under 2 seconds. I purged every unnecessary plugin I could. I integrated MaxCDN (which creates cached versions of your site, making it static) and WP Total Cache. It worked pretty well (once I finally got the settings right). The load time (about 2 seconds) wasn’t bad at all.
Still, Jekyll sites load pages in about .5 seconds. This load time can increase SEO, since Google ranks sites higher when it can load the pages faster.
Faster loading times also fit better with the way people use the web. People quickly jump from page to page trying to find information. If pages load quickly, you allow users to more easily move around your site and find what they need.
The fundamental paradigm of WordPress is flawed, I think. In WordPress, your content resides in a database, and your theme files reside in another folder on your server.
When a user makes a request for a page, WordPress’s template tags make a request to the database for the content. The database serves up the content and packages it into the HTML files. The display is then returned to the user.
Why build the site dynamically every time a user makes a page request? This is part of why WP is slow. It makes much more sense to build the entire site one time and then return the pre-built pages.
With Jekyll, you build your site first and then push it out to your server. Each time a user requests a page, there’s no need to make requests to a database to dynamically assemble a site. Your site is all ready to serve. (And there is no database.)
Of course it takes a while to build your site. And interestingly, Movable Type (an earlier competitor to WordPress) died out in part because the build time to recompile your site took a while.
But you can offload the build process to your web host by using Github Pages. Github Pages will automatically build your Jekyll site when you commit to your Github repository. Who cares if it takes a few minutes for Jekyll to build your latest commit. Once it’s live, you save a ton of time in delivering your site with each request.
I have a few other reasons as well:
Although I’ve migrated the content and gotten most everything working, I still have a lot of work to do. Over the coming months, I’ll be fine-tuning the rest of the implementation. However, I didn’t want to let the fine-tuning get in the way of my blogging. Content is the main reason people to any site.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.