I've just updated my site's HTML/CSS and moved from Twitter Bootstrap to Zurb Foundation. This post captures my subjective notes on the migration.
When I originally set this site up, I didn't know what frameworks existed or anything more than the basics of dealing with HTML (and barely any CSS). I came across Twitter Bootstrap and immediately decided it would Solve All My Problems. It really did. Since then, I've gone through one 'upgrade' with Bootstrap (from 1.x to 2.x), after which I dutifully ignored all the fixes and improvements (note that Bootstrap was up to v2.3.2 while I was still using v2.0.2).
For the most part, this was fine with me but for a while now, I've been meaning to make this site 'responsive' (read: not look like crap from a mobile). Bootstrap v3 purports to be mobile-first so upgrading would likely give me what I'm after but v3 is not backwards compatible, meaning I'd have to rewrite parts of the HTML. Since this step was unavoidable, it led me to have another look at front-end frameworks, just to see if I was missing anything. This was especially relevant since we'd just released the new OCaml.org website, itself built with Bootstrap v2.3.1 (we'd done the design/templating work long before v3 was released). It would be useful to know what else is out there for any future work.
Around this time I discovered Zurb Foundation and also the numerous comparisons between them (note: Foundation seems to come out ahead in most of those). A few days ago, the folks at Zurb released version 5, so I decided that now is the time to kick the tires. For the last few days, I've been playing with the framework and in the end I decided to migrate my site over completely.
Over time, I've become moderately experienced with HTML/CSS and I can usually wrangle things to look the way I want, but my solutions aren't necessarily elegant. I was initially concerned that I'd already munged things so much that changing anything would be a pain. When I first put the styles for this site together, I had to spend quite a bit of time overwriting Bootstrap's defaults so I was prepared for the same when using Foundation. Turns out that I was fine. I currently use Jekyll (and Jekyll Bootstrap) so I only had three template files and a couple of HTML pages to edit and because I'd kept most of my custom CSS in a separate file, it was literally a case of swapping out one framework for another and bug-fixing from there onwards. There's definitely a lesson here in using automation as much as possible.
Customising the styles was another area of concern but I was pleasantly surprised to find I needed less customisation than with Bootstrap. This is likely because I didn't have to override as many defaults (and probably because I've learned more about CSS since then). The one thing I seemed to be missing was a way to deal with code sections, so I just took what Bootstrap had and copied it in. At some point I should revisit this.
It did take me a while to get my head around Foundation's grid but it was
worth it in the end. The idea is that you should design for small screens
first and then adjust things for larger screens as necessary. There are
several different default sizes which inherit their properties from the size
below, unless you explicitly override them. I initially screwed this up by
explicitly defining the grid using the
small-# classes, which obviously
looks ridiculous on small screens. I fixed it by swapping out
medium-# everywhere in the HTML, after which everything looked reasonable.
Items flowed sensibly into a default column for the small screens and looked
acceptable for larger screens and perfectly fine on desktops. I could do
more styling of the mobile view but I'd already achieved most of what I was
Foundation also provides a component called Flex Video, which allows the
browser to scale videos to the appropriate size. This fix was as simple as
going back through old posts and wrapping anything that was
<iframe> in a
<div class="flex-video">. It really was that simple and all the Vimeo and
YouTube items scaled perfectly. Here's an example of a video from an
earlier post, where I gave a walkthrough of the ocaml.org site.
Try changing the width of your browser window to see it scale.
Another of the main difference between the two frameworks is that Bootstrap uses LESS to manage its CSS whereas Foundation uses SASS. Frankly, I've no experience with either of them so it makes little difference to me. It's worth bearing in mind for anyone who's workflow does involve pre-processing. Also, Bootstrap is available under the Apache 2 License, while Foundation is released under the MIT license.
Overall, the transition was pretty painless and most of the time was spent getting familiar with the grid, hunting for docs/examples and trying to make the image gallery work the way I wanted. I do think Bootstrap's docs are better but Foundation's aren't bad.
Although this isn't meant to be a comparison, I much prefer Foundation to Bootstrap. If you're not sure which to use then I think the secret is in the names of the frameworks.
That's pretty much how I'd recommend them to people now.Share / Comment
As some of you may have noticed, the new OCaml.org site is now live!
The DNS may still be propagating so if http://ocaml.org hasn't updated for you then try http://188.8.131.52. This post is in two parts: the first is the announcement and the second is a call for content.
The new site represents a major milestone in the continuing growth of the OCaml ecosystem. It's the culmination of a lot of volunteer work over the last several months and I'd specifically like to thank Christophe, Ashish and Philippe for their dedication (the commit logs speak volumes).
We began this journey just over 8 months ago with paper, pencils and a lot of ideas. This led to a comprehensive set of wireframes and walk-throughs of the site, which then developed into a collection of Photoshop mockups. In turn, these formed the basis for the html templates and style sheets, which we've adapted to fit our needs across the site.
Alongside the design process, we also considered the kind of structure and workflow we aspired to, both as maintainers and contributors. This led us to develop completely new tools for Markdown and templating in OCaml, which are now available in OPAM for the benefit all.
Working on all these things in parallel definitely had it challenges (which I'll write about separately) but the result has been worth the effort.
The journey is ongoing and we still have many more improvements we hope to make. The site you see today primarily improves upon the design, structure and workflows but in time, we also intend to incorporate more information on packages and documentation. With the new tooling, moving the website forward will become much easier and I hope that more members of the community become involved in the generation and curation of content. This brings me to the second part of this post.
We have lots of great content on the website but there are parts that could do with a refresh and gaps that could be filled. As a community driven site, we need ongoing contributions to ensure that the site best reflects its members.
For example, if you do commercial work on OCaml then maybe you'd like to add yourself to the support page? Perhaps there are tutorials you can help to complete, like 99 problems? If you're not sure where to begin, there are already a number of content issues you could contribute to.
Although we've gone through a bug-hunt already, feedback on the site is still very welcome. You can either create an issue on the tracker (preferred), or email the infrastructure list.
It's fantastic how far we've come and I look forward to the next phase!Share / Comment
We're close to releasing the new design of ocaml.org but need help from the OCaml community to identify and fix bugs before we switch next week.
Ashish, Christophe, Philippe and I have been discussing how we should go about this and below is the plan for migration. If anyone would like to discuss any of this, then the infrastructure list is the best place to do so.
We've made a new branch on the main ocaml.org repository with the redesign. This branch is a fork of the master and we've simply cleaned up and replayed our git commits there.
We've built a live version of the new site, which is visible at http://preview.ocaml.org - this is rebuilt every few minutes from the branch mentioned above.
Over the course of one week, we ask the community to review the new site and report any bugs or problems on the issue tracker. We triage those bugs to identify any blockers and work on those first. This is the phase we'll be in from today.
After one week (7 days), and after blocking bugs have been fixed, we merge the redesign branch into the master branch. This would effectively present the new site to the world.
During the above, we would not be able to accept any new pull requests on the master branch but would be happy to accept them on the new, redesign branch. Hence, restricting the time frame to one week.
Please note that the above is only intended to merge the design and toolchain for the new site. Specifically, we've created new landing pages, have new style sheets and have restructured the site's contents as well as made some new libraries (OMD and MPP). The new toolchain means people can write files in markdown, which makes contributing content a lot easier.
Since the files are on GitHub, people don't even need to clone the site locally to make simple edits (or even add new pages). Just click the 'Edit this page' link in the footer to be taken to the right file in the repository and GitHub's editing and pull request features will allow you to make changes and submit updates, all from within your browser (see the GitHub Article for details).
There is still work to be done on adding new features but the above changes are already a great improvement to the site and are ready to be reviewed by the OCaml community and merged.Share / Comment
Last Thursday a bunch of us from the OCaml Labs team gave an OCaml tutorial at the FPDays conference (an event for people interested in Functional Programming). Jeremy and I led the session with Leo, David and Philippe helping everyone progress and dealing with questions.
It turned out to be by far the most popular session at the conference with over 20 people all wanting to get to grips with OCaml! An excellent turnout and a great indicator of the interest that's out there, especially when you offer a hands-on session to people. This shouldn't be a surprise as we've had good attendance for the general OCaml meetups I've run and also the compiler hacking sessions, which Jeremy and Leo have been building up (do sign up if you're interested in either of those!). We had a nice surprise for attendees, which were uncorrected proof copies of Real World OCaml and luckily, we had just enough to go around.
For the tutorial itself, Jeremy put together a nice sequence of exercises and a skeleton repo (with helpful comments in the code) so that people could dive in quickly. The event was set up to be really informal and the rough plan was as following:
Installation/Intro - We checked that people had been able to follow the installation instructions, which we'd sent them in advance. We also handed out copies of the book and made sure folks were comfortable with OPAM.
Hello world - A light intro to get people familiar with the OCaml syntax and installing packages with OPAM. This would also help people to get familiar with the toolchain, workflow and compilation.
Monty Hall browser game - Using
js_of_ocaml, we wanted
people to create and run the Monty Hall problem in their
browser. This would give people a taste of some real world interaction by
having to deal with the DOM and interfaces. If folks did well, they could
add code to keep logs of the game results.
Client-server game - The previous game was all in the browser (so could be examined by players) so here the task was to split it into a client and server, ensuring the two stay in sync. This would demonstrate the re-usability of the OCaml code already written and give people a feel for client server interactions. If people wanted to do more, they could use ctypes and get better random numbers.
We did manage to stick to the overall scheme as above and we think this is a
great base from which to improve future tutorials. It has the really nice
benefit of having visual, interactive elements and the ability to run things
both in the browser as well as on the server is a great way to show the
versatility of OCaml.
js_of_ocaml is quite a mature tool and so it's
no surprise that it's also used by companies such as Facebook (see the recent
CUFP talk by Julien Verlaguet - skip to 19:00).
We learned a lot from running this session so we've captured the good, the bad and the ugly below. This is useful for anyone who'd like to run an OCaml tutorial in the future and also for us to be aware of the next time we do this. I've incorporated the feedback from the attendees as well as our own thoughts.
Most people really did follow the install instructions beforehand. This made things so much easier on the day as we didn't have to worry about compile times and people getting bored. A few people had even got in touch with me the night before to sort out installation problems.
Many folks from OCaml Labs also came over to help people, which meant no-one was waiting longer than around 10 seconds before getting help.
We had a good plan of the things we wanted to cover but we were happy to be flexible and made it clear the aim was to get right into it. Several folks told us that they really appreciated this loose (as opposed to rigid) structure.
We didn't spend any time lecturing the room but instead got people right into the code. Having enough of a skeleton to get something interesting working was a big plus in this regard. People did progress from the early examples to the later ones fairly well.
We had a VM with the correct set up that we could log people into if they were having trouble locally. Two people made use of this.
Of course, It was great to have early proofs of the book and these were well-received.
In our excitement to get right into the exercises, we didn't really give an overview of OCaml and its benefits. A few minutes at the beginning would be enough and it's important so that people can leave with a few sound-bites.
Not everyone received my email about installation, and certainly not the late arrivals. This meant some pain getting things downloaded and running especially due to the wifi (see 'Ugly' below).
A few of the people who had installed, didn't complete the instructions fully but didn't realise this until the morning of the session. There was a good suggestion about having some kind of test to run that would check everything, so you'd know if there was something missing.
We really should have had a cut-off where we told people to use VMs instead of fixing installation issues and 10-15 minutes would have been enough. This would have been especially useful for the late-comers.
We didn't really keep a record of the problems folks were having so we can't now go back and fix underlying issues. To be fair, this would have been a little awkward to do ad-hoc but in hindsight, it's a good thing to plan for.
Overall, it was a great session and everyone left happy, having completed most of the tutorial (and with a book!). A few even continued at home afterwards and got in touch to let us know that they got everything working. It was a great session and thanks to Mark, Jacqui and the rest of the FPDays crew for a great conference!
(Thanks to Jeremy, Leo, David and Philippe for contributions to this post)Share / Comment
If you're starting from scratch, installation can take some time so it's best to get as much done in advance as possible. You'll need OPAM (the package manager), OCaml 4.01 (available through OPAM) and a few libraries before Thursday. If you have any issues, please contact Amir.
OPAM: Follow the instructions for your platform at http://opam.ocaml.org/doc/Quick_Install.html.
OPAM requires OCaml so hopefully the relevant dependencies will kick in and
you'll get OCaml too (most likely version 3.12). You can get a cup of
coffee while you wait. After installation, run
opam init to initialise OPAM.
OCaml 4.01: We actually need the latest version of OCaml but OPAM makes this easy. Just run the following (and get more coffee):
$ opam update $ opam switch 4.01.0 $ eval `opam config env`
pkg-config. This will depend on your platform so on a Mac with homebrew I would do
brew install libffi pcre pkg-configor on Debian or Ubuntu
apt-get install libffi-dev. After this, two OCaml packages it's worth installing in advance are
js_of_ocamlso simply run:
$ opam install core js_of_ocaml
OPAM will take care of the dependencies and the rest we can get on the day!Share / Comment