Sara Soueidan

I Wrote A CSS Reference.

Published
Estimated Reading Time:

Yesterday, we finally released a long-awaited project over at Codrops: Codrops' new CSS Reference, authored by yours truly. Even though I wrote a post over at Codrops introducing the reference and its features, I want to share a little bit more about my experience writing it.

Please note that as of January 2016, I am no longer the maintainer of the Codrops CSS Reference.

Thus, unlike my usual highly-technical blog posts, this is a (possibly-boring, but short!) post sharing a little more about the CSS Reference and how it came to be, and answering a couple of questions I got via Twitter since the release.

I started writing for Codrops in 2013. Some time at the end of the year, I was thinking to myself: “Codrops would be an ultimate CSS reference if it had a CSS reference” (no pun intended). I thought that it would be fantastic if we had a CSS reference at hand for when someone needs to learn more about a specific CSS property used in one of the many creative demos found there. This idea came to my mind since I used to google for some of the properties I saw in the Codrops demos when I first started learning CSS and checking Codrops out regularly.

Around the same time that year, Manoela approached me with the same idea. It was an idea in my head, and part of a vision that Manoela and Pedro have for Codrops. It was only a few days later that I started digging into CSS specifications and writing the reference entries.

It took around 7–8 months to finish all of the entries. During that time, I had little time for side projects, but I did keep writing—albeit sporadically—on my blog and other blogs such as A List Apart, among others.

One of the main reasons I looked forward to starting the journey of writing the reference was knowing how much I will learn in the process. For me, that was enough of a reason to instantly say yes when Manoela approached me with the idea.

One of the main reasons I looked forward to starting the journey of writing the reference was knowing how much I will learn in the process.

I knew it was a chance for me to know much more about CSS than I would otherwise know in such a short period of time. In order to write the description and information about a specific CSS feature, I had to dig deeper than I usually do into the specification where that CSS feature is defined.

As many of you may know, the specifications don’t always contain everything you need to know about a property, and the writing style is not always the clearest (which is one of the reasons we wrote the reference, too!), so I had to do a lot of research for many of the entries, reading great resources here and there, picking up a lot of knowledge and getting a lot of “ah-ha” moments in the process. There was a lot about CSS that I didn’t know, and that I still don’t know.

I wrote the CSS entries the same way and same style I usually write my articles. Now, some entries are exceptions because they don’t require a lot of elaboration. For example, properties like border-color are self-explanatory, so the tone of those entries is more “official” and less “me”.
So, if you happen to enjoy my writing style, I can tell will enjoy reading the reference entries too.

Manoela and Pedro gave me a lot of freedom and flexibility to write the reference at my own pace and my own schedule and time, making sure I still had the time to work on other things as well so that writing the reference does not limit my creativity, my other client work, my blog, and, of course, my life!

I can’t even begin to describe how excited I was to finally get to the point of releasing the reference! I usually get super nervous (read: almost get a heart attack) before publishing a blog post on my own low-profile blog, so publishing more than 300 short to long articles on Codrops was extremely overwhelming and nerve-wrecking. I can always hear my heart beat when I tweet about a new blog post, and I certainly did when we finally got the word out about the reference.

It took us a little over a year to release the reference because of the amount of work each of us at Codrops had, besides the reference. 2014 was the year I started speaking at conferences, and in the second half of it (i.e. after having finished writing the entries) I got my hands full with conference work, writing, and other stuff that took my attention away from the reference for some time. But we finally made it.

I got a few of questions from followers and commenters, and two of these questions kept popping up.

Is it “the new MDN”?

No, it’s not. At least it wasn’t our goal to make it so. It’s not even meant as competition to any other CSS Reference out there. It is simply another knowledge base added to what Codrops already offers on a regular basis.

I write about CSS (and SVG) a lot—be it on my blog, on Codrops, or one of the several other places I write at. The CSS Reference is, for me, simply an archive where I collected blog posts about a specific topic (CSS, in this case), and organized them in a way that is easier to browse and simpler for my readers to find what they are looking for.

The CSS Reference is, for me, simply an archive where I collected blog posts about a specific topic (CSS, in this case), and organized them in a way that is easier to browse and simpler for my readers to find what they are looking for.

I sometimes even think of it as a book! Instead of writing a printed CSS book, I wrote an online book, that is open to your contributions and suggestions via a Github repo that we shared on Codrops. So it has an advantage over a regular book in that you, my dear readers, get to pinpoint any miskates, errors, ask for additions and suggestions, etc.

Why didn’t you contribute to MDN instead?

I honestly don’t understand the reasoning behind this question. I mean, why would I not write the reference and choose to contribute to MDN instead?

That being said, I did mention a few reasons earlier why I chose to write the reference. Add to those that I love Codrops, and Manoela and Pedro gave me a lot of freedom and flexibility to give the reference its own character and style. They asked me to write it because they liked my writing style, and thus gave me the freedom to structure the entries the way I wanted. We did have some specifics—for example, the sections for the official syntax, browser support, etc. that we needed to have in every entry, and the rest was all up to me to write my own way.

Now, I don’t know if MDN would have allowed me to do the same, but Manoela knows how much I value the freedom and flexibility of work in my work, and she gave me just that, making the experience much more enjoyable, and feeling a lot less as a task or job.

Writing the CSS reference has been a wonderful experience, and I am happy to have gotten the chance to do it. I know I haven’t literally written a book here (as in: a printed book), but I like to think that I have—maybe because it makes me feel a liiiitle bit less guilty for not having started writing my SVG book yet!

I wholeheartedly hope you like it, find it useful, and learn from it as much as I have learned from writing it. Your feedback on Twitter, in the comments and your contributions in the Github repo have been amazing—thank you so much for your support!

And thank you for reading this post, and reading the reference entries in the future.

–S