During my internship at Phusion I worked on improving the Passenger Library as my final assessment to graduate from Communication and Multimedia Design. Phusion received feedback from users having a hard time navigating through the Library, and finding basic content. I wanted to try and solve that.

A use case for React
An important choice for the new design was giving users the option to select the language and integration they wanted to read about. The old Library makes you choose the same option several times and can sometimes isolate you from that choice. By adding this option to the navigation on the left, users wouldn’t have to face this problem anymore.

In the Docs we recently launched, almost all content is based on what choices you make. This level of interactivity reminded me of web apps. And when we're talking about web apps, React immediately comes to (my) mind. With React I would be able to set up a state that rules all, which is exactly what these choices are suppose to do. I pitched the idea to build a prototype in React because I didn’t have a lot of experience with it yet, and the use case seemed like a good fit.

Phusion agreed that it would be a good learning experience but they were on the fence about using React. Phusion was already using Middleman to create its Passenger Library. For React to take its stead, it'd need to bring about plenty of upside. And in finding out what the right tool for the right job is, we decided to give React a shot to evaluate it against Middleman for our use cases.

We went with Middleman
To be honest, both options would have worked out just fine. One deciding factor was that Middleman had a more flexible Markdown option. In the end our team just has a lot more experience with maintaining a Middleman (Ruby) project.

Using the virtual dom makes React feel very smooth and app-like. However, its perceived performance had a down side in our case.

Middleman’s performance VS React's perceived performance
Since Middleman generates static files, and doesn’t use a ton of Javascript to render the page, I can only assume that Middleman has better performance. That said, the perceived performance of React is a whole different beast. Once your app is on the screen everything feels faster, and from a UX point of view this absolutely has my preference.

There is something to be said about loading your first page as quick as possible though. Research shows that a millisecond of loading time can make all the difference to your user deciding to stay or not. However, I think in our case this wouldn’t matter that much since most of our website is plaintext, and some pages use Javascript to redirect you to the preferred integration or language in the beginning.

While the perceived performance feels nice, it does hold some risks in our case. Like how the language and integration selection can change the article that you are currently reading. With React’s virtual dom this change happens fluently without refreshing the page.

The user might change the language from Ruby to Python only to see nothing happen. It could be that some text content doesn’t change in the users current viewport. This might result in the user thinking the selection didn’t do anything or worse, that it didn’t work.

Changing from Ruby to Python in our solution will result in a redirect and thus a “page flash”. While this doesn’t feel as smooth as React’s virtual dom, it does give the users a cue that their selection had impact and thus improving their experience.

Conclusion
Migrating from React to Middleman showed me that a migration can bring problems that go beyond writing code. I recommend developers to think about the UX too when implementing frameworks and libraries.

It's been a long ride but with the help of the Phusion team we proudly launched the new Passenger Docs just last week.

If you have any suggestions of improving the Docs you can help us out by using the feedback box, or by submitting an issue on GitHub. Seeing as the Docs are completely open source you can also contribute yourself, and I would love to see your suggestions on improving the Docs or its source code.

Need help with your UI/UX designs like we showcased in this blog post? Or other development / optimization / training services for your (web) applications? We'd love to help; check out our Phusion® Consultancy page for more info.