The design principles of wordsandbuttons.online

Five months ago I stopped blogging on Medium and started http://wordsandbuttons.online/ — a growing collection of interactive tutorials, guides, and quizzes about maths, software engineering, and programming languages. It has been doing well so far gathering more than 150 000 reads with its 15 pages published in 5 months.

Apparently, interactive media works slightly better than just text and pictures.

On a regular blog this is just a picture. But on wordsandbuttons.online you can drag the points and see what the curve would do: http://wordsandbuttons.online/programmers_guide_to_polynomials_and_splines.html

But that’s just vanity metrics. The most important goal of the whole thing is the experimentation for the sake of experimentation. I want to gather expertise in this new media before it becomes mainstream.

And this dictates some rather unusual design principles for the project.

Principle o. The design should only follow the goal

All the design principles should follow the final goal and nothing else. Previous experience, voice of authorities, fashion trends of the majority, personal preferences, fears, and neuroses, — neither of them get a vote.

Principle 1. No third party code

Usually, a project starts from selecting 3rd-party libraries. You don’t want to re-implement everything from scratch once there are ready-made solutions waiting for you.

Unless you want to experiment with things. In this case you don’t want to find yourself caught in other’s constraints. The whole point of gathering expertise is to become better than everybody else in something, not to get stuck with UI or the algorithms you don’t want.

So no 3-rd parties.

It could have been a wrong decision regarding development velocity. Yet 15 pages in 5 months developed by a single engineer in his spare time is a pretty good pace. Also, the writing is the bottleneck for wordsandbuttons.online, not the development. There is no reason to speed the coding up if there is nothing to code.

Principle 2. Copy-paste instead of code reuse

I want to change stuff constantly to see what happens and I don’t want my older stuff to be broken. That’s the whole point of gathering expertise. You should know more tomorrow than you know today, therefore your today’s code is crap by tomorrow’s standards.

You don’t want to reuse crap, so don’t reuse anything at all.

Yes, there is a backside. Sometimes you feel shame for your earlier code and you wish it to get better automagically. But I did a few micro-renovation projects on my older pages, and it didn’t take enough much time to make any kind of automation necessary.

Principle 3. Naming is more important than code

This is a growing project. Moreover, it has no structure, it’s basically a collection of pages. A bucket of things. It’s very important to keep things searchable, and for this, you want good consistent names.

The only way to make it happen is not to reinvent names for things that are already there. If there are spline2, there should be spline3 and not cubic_spline or s3_polynomial_b. The latter might be better in general context, but the project creates context on its own.

Unfortunately, just like with the code, you can’t expect your naming to be better today than it would become tomorrow. But you shouldn’t change it too much either.

And that’s why naming is more important than the code. It deserves more attention. If you went wrong in the code, you could just leave it there and move on. Or you can get back and fix it. It’s just one page, it’s isolated, it lives by its own. But the names are not isolated. Names bind the expertise I’m gathering together.

Principle 4. Principles will change

Just as with the code, my today’s principles are crap.

The whole point of the things is the experimentation. I found that these things work for the project as it is now. But I expect them to evolve in the future along with the project. Otherwise I’m not doing my job right.