For some time now, we’ve been exploring adding support for Markdown to issue descriptions and comments but held off for a variety of reasons. Once we decided to add it, my initial thinking was that it would be fairly straightforward to add. I mean, all we would have to do differently is add another filter to how we render content. Simple. Right?
Rendering
Once I started putting together a plan to fully scope out the effort, I quickly realized that it was going to be about much more than simply updating the rendering. We had existing tests that would have to be updated, and new tests would have to be added. We also couldn’t just use a standard Markdown formatter out of the box because some elements like headings and horizontal rules wouldn’t be a good fit in the larger context of an issue detail page.
Styling
The second significant change was making sure that the rendered HTML elements looked right once they were rendered. Dumping out code, block quotes, and lists would render passably, but all of these elements were going to need a little extra styling to look right. Moreover, it wasn’t just about rendering in a web browser. These elements also needed to look good in emails.
Previewing
To really implement Markdown correctly, we’d need a way to preview your content. While most developers and technical users are familiar with Markdown, it’s just complex enough to lead to errors. Adding Markdown without preview for checking your words didn’t make sense. 1 & 2 Fortunately, preview was a feature that we wanted to add anyways, but there were still a few things ahead of it in the queue. Once I started planning out our previewing, the big question was client-side previewing or server-side. Since Sifter’s comments auto-link to other issues, some of our rendering logic couldn’t be replicated client-side. So server-side it was.
The catch with server-side previewing is that it’s going to be slower. So, my first approach was to just regularly update a hidden preview in the background as you type. However, given the delay for the server to respond, things could either slow down if the typing got too far ahead of the preview, or we could end up making a bunch of additional and unnecessary requests. Neither of these would work, but waiting until the person was done typing meant that there would likely be a short delay when they chose to view the preview. (Currently, the server is responding to these requests in about 25ms on average.) The end result was that we decided it was OK to wait a fraction of a second for the preview to render.
Formatting Tips
Once we worked out previewing, we needed to let folks know what was possible now. So we needed a page of formatting tips to show the subset of Markdown that Sifter supported. 3 Something like this needs an affordance to let people know where to find it as well as a page with all of the content to explain it. So we had to work in a link to the “Formatting Tips” as well as create the page. It’s a minor detail, but just one more little thing to increase the scope.
Potentially even more?
All-in-all, it’s not that complex, but compared to my original thinking, it quickly changed and evolved. In discussions with customers, we’ve also already started anticipating potential challenges. While Markdown is generally harmless if you’re not aware of it, there are times where it can jump in and create unanticipated problems for those not familiar with it. Ultimately, our choice in that regard was to create a user preference or just accept that there will be some occasional inconveniences that will be far-outweighed by the increased productivity of everyone else using it. We’ll be keeping a close on this via support channels.
The other element where stopped just a little short is colored code formatting. This is something we started digging into but weren’t quite sure about whether we wanted to go there just yet. It’s an idea that we like, but if we add it down the road, we wanted to make it a dedicated project unto itself so that we could really fine-tune it and make it work well instead of just bolting it on to the Markdown release.
Taking it Slow
It’s always tempting to add features, make promises, and underestimate the amount of effort involved in seemingly simple changes. More importantly, adding features isn’t a one-and-done sort of thing. New features have an impact on support and almost inevitably create even more feature requests as folks come up with ideas how to improve the feature even more. Every feature deserves careful consideration as the impact and ripple effect can often extend much farther than might appear at first glance.