View on GitHub

Vorner's random stuff

Design guidelines: General principles and project statement

There were some heated discussions in Rust community as of late. During that discussions, I argued that some best practices for RFC authors would improve both on the results as well as the discussions and I promised to give it a try.

However, I’m not an RFC author myself (a suggestion to include stabilization FPCs in TWiR doesn’t really count). Therefore, my authority to write about how a good RFC looks like is severely limited. So I thought I’ll write a blog series about designing things. I do quite a lot of that and RFC is just a special case of design.

In the long term, I’d like to consolidate the blog posts to something more. There’s a lot of learning books about Rust:

But there’s not much on design ‒ on what you do before you start writing the Rust code. That phase is probably more important than understanding some syntactic tricks.

So I’d like this to grow into some kind of guide (I don’t know exactly what kind yet). But I’d like input from other people on this (because others may know different things and because I still feel this text needs improvements). If you are interested in helping out, contact me on vorner@vorner.cz ‒ we can talk about some form this could have and how to go about it.

For now, I have some of my own personal observations what worked for me. It is a collection of things I learned from the Internet, several books and practice (I can’t claim much originality here). And what works for me doesn’t have to work for you. If you have something that works better ‒ well, see the above paragraph. Also, as with any guidelines, it is appropriate to go against them from time to time. Use your own common sense. And it is certainly not a silver bullet ‒ it might help you improve, but following it isn’t guaranteed to produce a good design on its own.

General principles and attitudes

Design is usually team work. Even if there’s one person dedicated to making the design, others comment, try to find problems in it or validate it. And other will be implementing it.

Therefore, there’s a lot of non-technical stuff around design. Emotions. Misunderstandings. Politics. Usually, I try to avoid them as much as possible, but they are still there, we are still human. My goals are usually to have a good solution to a problem, not gaining points in corporate power struggles. So, good design is as much about the technical aspects as about psychology, negotiations and keeping one’s sanity.

There are usually people that argue hard. I know I do, sometimes. It’s not because I’d like arguing, but sometimes I feel there’s a need to do that. But if there are good factual arguments at table, if all the parties try to communicate in a clear way, it goes smoother. And remember, these disagreements are professional, not personal ‒ you still can go to lunch and have a good chat about cars (or whatever else) even if you disagree with each other.

So here are some little overall tips to lead a good discussion:

Problem statement

So, you’re designing something. But first you need a clear idea what it is. This is where a problem statements is a very valuable tool. The Rust RFC process asks to include a motivation and it is a good requirement. But I prefer problem statement over a simple motivation. While it is about the same thing, there’s a different framing.

In other words, you should have a very clear idea what problem you’re solving. Bugs are easy to state as problems. But even features can be described as problem statement (or user story). So, don’t say the word processor needs to be able to save documents. Say that if it can’t users have to type their documents every time from scratch. This is a bit to the extreme ‒ we all know why word processors can save documents. But oftentimes, what seems obvious to you (because you spent some amount thinking about the problem) doesn’t even cross the minds of others.

This is not to say you can’t do anything just for the fun of it, but you should know it.

As for the form, be as specific as possible, give examples, show demonstrations. If you think everyone should already know what you talk about, because there were previous discussions about that thing, at least reference the discussions. If you don’t, they’ll assume what you gave them is everything relevant (it’s called WISIATI by psychologists).

If you yourself don’t have that problem, talk to someone who does (the user). If people complain about UX of your product, grab a random person, put the product into their hands and write down during which activity they cursed the most. Make sure you understand what their problem is, write it down and let them cross-check it. Ask them to show the problem to you, make a screenshot, … But know it’s impossible to fix if everything you know is „It’s broken“. A good problem statement and a good bug report share many common qualities.

I’d even argue that a good problem statement is the hardest part and also the most important part of the whole design process. Make sure to write the problem statement down, not only have a vague idea what it is. It’ll give you these benefits:

While you can go back to this point during your next phases (because you experiment with something and it turns out the problem is slightly different, deeper, …), you should not skip it. By doing so, you risk going in circles, finding solution to a non-problem, arguing infinitely if others like your solution or not or other undesirable things.

Of course, the size of the problem and the solution also influences how much effort goes into this phase. Smaller problems deserve less attention.

Oh, and avoid doing this after you have the solution. You’re as likely to come up with some problem the solution solves, even if nobody was ever bothered by it.

Next issues

I’d like to cover these in some future posts (not necessarily in this order):