Hurry to get Markdown awesomeness?
We, developers, often feel comfortable with technologies we already know. That is a fact, and this is related to the idea of comfort zone, a behavioral space where “we feel at home”. We master our tools so much that we have developed patterns we continuously repeat, so that stress and risks are minimized. When we read an article about a new cutting edge tool or language we don’t know, we often say: “I should try this one day”. But it is not that easy to step up and take the time to follow our dreams: when a new project arrives in our bucket, we often choose security and efficiency of already-known-and-mastered-techs.
Several studies (e.g., this one) show that we tend to adopt a steady level of performance given a certain comfort. Yet, to improve ourselves, we need a state of relative anxiety. That is another space, just outside the confort zone. Pushing the boundaries of our comfort zone is important, and given how fast things evolve in our domain, it is even a requirement!
To level up and satisfy our curiosity, we decided to open Le lab, a week per month. Le lab is our place to experiment foreign technologies (i.e. languages, paradigms, frameworks, and so on) by designing and implementing a product given the following constraints:
- Time matters: we only have a week. One. Single. Week. To release a MVP;
- Quality matters: being short in time is not an excuse, every implemented feature must be tested, and continuous integration must be configured. Ideally, deployment should be automated too;
- Feedback matters: our brand new product should be publicly exposed and testable. We must not be ashamed to show what we did in a week with a tool we are not comfortable with. If something goes wrong with our application, we want people to drop us an email.
If you plan to do this at
home work, here is a typical week
organization plan (which may evolve in the near future based on our experience):
- Previous Friday morning (day #0) should be dedicated to brainstorm about the MVP you want to develop and the technologies you want to explore. This lets the week-end to re-think about it as a background task. By the end of this first meeting, you should exactly know what will be your application stack, its features, and the constraints you want to set to yourselves. It is allowed to plan for more than a week: features will stay in your backlog for another session;
- Monday (day #1) is the day reserved to read, learn, and read. And learn. You can hack a bit if you wish to;
- Things start to be serious from Tuesday (day #2) to Wednesday (day #3) evening: this is where you must be productive;
- Thursday (day #4) is the day reserved to sum up your work in a blog post, and to fix the bugs found before publicly releasing your work;
- On Friday morning (day #5), re-read your blog post, and put a final make-up to your MVP. It is time to reveal to the world your intensive work.
Go get a drink with your colleagues. Have a rest. Enjoy life. You did a great thing this week!
Monod, TailorDev’s Markdown Editor
TL;DR The first experiment we wanted to tackle was a Markdown editor with real-time preview. The week #1 release had to be a pure client-side application written with React.
As mentioned before, the previous Friday meeting gave directions for the problem we wanted to address. After digging around, we found a key problem to solve during this first Le lab session.
Here, at TailorDev, we love Markdown. Maybe it’s a Stockholm syndrome due to the fact that we, developers, live in a Markdown world. Whatever the reason is, every text document we produce is a Markdown document. This blog post source is a Markdown document. Every official letter we write, every business resources we write, are Markdown documents.
We love Markdown because:
- it’s simple to learn (even for non-tech people),
- it’s simple to integrate in a Git-collaboration workflow, and,
- it’s “relatively easy” to export into various formats.
The two last points are not totally true: it depends on your operating system, and the time you want to spend installing a bunch of stuff to edit, version, and compile a Markdown file into PDF with a custom CSS stylesheet. That is the first problem we want to address here:
Markdown to PDF with styles… For Humans ™.
When we started to brainstorm about the editor’s most desired features, fancy ideas came out of the hat like multi-users support and real-time collaboration. We were far from a work-week here, but it did not matter: it was an enjoying moment for the team, really stimulating.
For this first session, and among all the features in our backlog, we decided to focus on:
- Markdown edition with syntax highlighting;
- Real-time rendering preview (with styles);
- PDF export, because we do have a printer at work, and we shall use it;
- Persistence of the content because no one likes loosing her work.
For this first session, we tackled the problem of building a product with
React, Facebook’s awesome library for
building user interfaces. The good thing of starting with React nowadays is that
we do not have to choose between
v0.14, to replace our
with something else, and that a reasonable amount of documentation is now
available. Learning React is really entertaining as we have to slightly change
Additionally, we wanted to give new dev tools a try. We know both
Grunt and Gulp well, so why not
trying webpack instead? Because we are in 2016, we
wanted to write ES6 code too. Don’t know what it is? Check out this
page. Since we cannot properly execute ES6
code in most of the current browsers, we have to transpile it, which seems to be
Babel’s job. As for testing, we chose to use
mocha + chai, which we know, but
combined with Enzyme, Airbnb’s testing utility for
At TailorDev, we mainly rely on CircleCI for
continuous integration. That is what we did for Monod too. Wiring GitHub and
CircleCI was a no-brainer, and we even added Heroku
deployment. In about 10 minutes, we
had solved a common issue in many organizations, that is how to deploy
software. Configuring a test
suite (even empty) at the beginning, along with continuous integration, promotes
the writing of tests. In addition, we added two
npm tasks to manually run the
test suite (with a
watch option) so that everyone could run the test suite on
her own. The most important thing here is that these commands must work for
everyone, otherwise do not expect your teammates to write tests.
In order to deploy our application, we needed a way to create a build (also
known as artifact), i.e. given a state of the source code, we wanted a
production-ready version of this state. That is webpack’s responsibility. The
most complicated task was to write the
webpack.config.js file. To be honest,
we are still not comfortable with it. We chose to split the configuration into
two parts (
build), merged with a
common configuration shared by
both parts. We borrowed SurviveJS’s idea here, but it
might not be our best idea.
On day #2, we were able to:
- push code to a repository
- write ES6 code, transpiled by Babel
- use a
devenvironment with hot reloading thanks to
- generate a build thanks to
- run a test suite, or having it automatically ran by CircleCI
- deploy code to Heroku when the test suite is “all green”
We spent almost an entire day on this part, but it saved us a lot of time during the next days since we did not need to update the configuration. That is our definition of being pragmatic. We believe that such a time could be reduced either by better knowing the tools and/or using a boilerplate. In addition, it is always better to understand how things work under the hood before taking shortcuts.
At this point, we were all set to build Monod. We started by drawing the
interface on a whiteboard, which helped us define the different React
App embeds the
Footer components, and the
one contains both the
component wraps CodeMirror thanks to a third-party
React component. The
component relies on marked as well as
emojify.js (which will be replaced by
Emoji One soon). Last,
localForage has been helpful to
easily implement a basic persistence storage at the
App component level.
After more than a hundred commits and several Pull Requests, we were happy to
v1.0 on Day #4. We even made a Pull Request on
third-party React component we used. That is what Open Source is after all,
We faced several issues and technical challenges during this first Le lab
week. For instance, synchronizing the scrolling between the
Preview components was not as easy as it seemed to be. That is why we do not
provide bi-directional synchronized scrolling yet. Still related to the
scrolling feature, there are a few remaining glitches we have identified, and we
are already working on it.
Last but not least, we spent the last day trying to optimize our application to
make the user experience as smooth as possible. For instance, we designed a
technique to asynchronously load the dependencies of a React component, which
will be described in another blog post.