About life, freedom and the pursuit of happiness user API

We are constantly confronted with systems created by other people. Whether it is the UI of applications in a smartphone or the cloud infrastructures of the modern Internet - it is the process of interaction that determines our feelings, impressions, and ultimately - the attitude to technology. We can be in the role of engineers, developers or ordinary users - user experience is important everywhere. A society with good UX creates a society of happy, contented, and productive people; a bad UX only leads to pain and suffering.

Even if you do not deliberately give yourself an account, then by creating a new software, you must create a user experience. When the code is already written, people begin to interact with it. Maybe these are the developers from your team. Maybe these are mobile developers who are trying to use your API, or system administrators who are trying to figure out why everything is broken on the night world tenure. The examples themselves may be completely different in essence, but the general principles apply to them. In this habropost, we’ll talk about ideas about UX, API design, learning psychology, and other related areas. Consider the use of good practices at various levels of application development. Whatever you do - write databases, libraries, hypermedia API or mobile applications - sooner or later someone touches your code - and let him get pleasure from it, right?

The report of Dylan Beatty at DotNext 2017 Moscow was used as a prototype of Habropost. It is one of the three best reports (according to participants' comments ). Dylan has been creating websites since the distant 1992. The ninety-second year, from the point of view of web application development, is indeed an ancient time. He is the owner of Microsoft MVP in the category of Visual Studio and Developer Technologies. In his hometown of London organizes events. NET User Group. Dylan is always time for communication and exchange of ideas, so you can write him on this email: dylan@dylanbeattie.net , go to the website: www.dylanbeattie.net or comment on twitter: @dylanbeattie .

Happiness

Today I would like to talk with you about the idea of ​​a "happy" code. The company Spotlight, in which I have been working for 15 years, has been engaged in show business, which includes acting, television, cinema, etc. In this medium, there is one generally accepted clip-art depicting two Greek theatrical masks - comedy and tragedy (or joy and sadness). During my professional career, I witnessed various projects. There were those who seemed to deserve success in all respects. They had everything: a great team, an interesting challenge, good technology, etc. But, oddly enough, these guys were failing. After some three months they came to their office and there they did not expect anything except a huge sea of ​​problems. And other projects, on the contrary, seemed crazy at the start. They didn’t even have money — only two people and one overwhelming task. And in absolutely incredible ways, these projects succeeded. Three months later, the team had a posh product, while their spirit was on top, the case was burning in their hands, the tasks were solved quickly one after another. There is something to think about. In my opinion, those teams that are forever ill, who don’t like to come to work, are hard and they only do that they wear themselves further - these teams produce bad software. Conversely, those teams that are positive are supplying good products. Throughout my career, I have not seen any such team in which people would have their work, still producing excellent IT systems. I decided to investigate this question and try to understand how to make the teams happy. After all, it is not about, say, buying table football in the office. Understand that most programmers like to code . These people came to programming for a reason, but because once they sat at the computer and realized that they were very interested. And the fact that they can earn their living on this bread is a great success for them. But experience leaves its mark. And what this imprint is like and how it affects the happiness of a programmer will be discussed with you today.

Detectability and dopamine

Detectable system is such a system, the work of which you can freely and independently. It is not scary to interact with such a system: it will not allow you to do something irreparable, because it is configured safely, on the sandbox principle. Moreover, such a system usually actively offers you ways to master it - and not boring, but fascinating, such as if you have a toy or a puzzle in your hands. One of the advantages of such a system is that it really does not require any training manuals or documentation. But there is another feature. Imagine such a situation. You sit at work and start fixing bugs. One fix, another third. You feel that the work has gone, and now you will not stop, as with Super Mario - try again and again. Time is 3 o'clock in the morning, and you still dare. A study was conducted, which showed that at the moment when a person manages to solve the problem, there is a surge of dopamine in his brain. It is known that the same substance is responsible for the sensations experienced by the gamer when he wins again, as well as the drug addict preparing to take a dose. Thanks to dopamine, a person learns things faster and better, knowledge remains for a longer period and is more easily applied in practice.

It turns out that if we create a system, working with which the programmer will feel as if interesting tasks and puzzles click one after another, he will experience these small dopamine emissions - he will work more productively and professionally.

Learning curve

In psychology, there is such a thing as a learning curve. It shows the relationship between the amount of time spent by a person studying a particular thing and the degree of competence that it has acquired.

Here are two curves: blue - with a steep climb and red - more gentle. Which one is better? Opinions are usually divided in half. Someone prefers to go along the "steep" path: to make a difficult breakthrough, but to achieve results faster. Such people learn Haskell language in 24 hours. Others advocate a slower, but “even” learning process. These are those who have been using Microsoft Word all their life, but for the time being do not know how to make a page break. Both methods are not bad and have the right to exist.

Taboo number 1: areas of decline

A common problem is a curve of this type:

The plot of the recession of the chart, immediately following the local peak, reflects the situation when the user is forced to roll back, because during the study of the material he understood something was wrong and now he has to relearn. The one who was engaged in ASP.NET WebForms probably remembers how easy it is to master one by one OnClick, OnItemDataBound, etc. And now you already feel that you have learned how to make websites. But then the boss tells you to connect a streaming media system and set up a video broadcast. You enter Visual Studio, you are looking for control of streaming media here, but do not find it. ASP.NET WebForms has created a narrow, specific idea about the web. Probably, the abstraction embedded in it was designed to lure VB developers into web programming. Because everything that ASP.NET WebForms operates on is buttons, events, clicks, data binding. And it turns out that you need to understand HTTP and HTML, requests, responses, stateless protocols, and more. So you find yourself on the very peak of the curve. And most likely, on this day you will leave your work in a bad mood, knowing that you have spent your strength in vain and now you have to start all over again. Nobody likes working like this.

Taboo number 2: curve jump

Another scenario, which is desirable to avoid, is as follows:

This is a kind of collision with a brick wall. You have already started to get used to it, and suddenly something incredibly complex appears on your path that is beyond your comprehension, and you are safely stuck. I remember how I was first explained the concept of recursion in functional programming. I completely understood nothing. I was advised to just train - to apply it again and again. But this is a dubious approach. In theory, this is not even a jump, but a break in the curve:

In fact, there is not one, but two curves. Getting from one to the other is a tangible difficulty for you. And overcoming this abyss you find that it is just as difficult for you to help someone else in this. Any concept really see through. Recursion is a Y-combinator - sooner or later you will “light up”. I personally, for the time being, do not understand the monads, although it is clear that one day I will overcome it. A person can do a lot. And nevertheless, we should try to develop our systems so that the user who studies it, if possible, does not encounter particularly difficult obstacles.

User experience

I first thought about UX while working with the Castle Windsor product. After downloading and installing it, I inserted the code taken from some training blog into the field, pressed F5 and saw this error:

I read the entire text. "Looks like you forgot to register your HTTP module ...". Pay attention to how friendly you are treated. The developers did not just throw you a mistake. They seemed to know that you would probably have little understanding of what you were working with, and therefore in the comments brought a piece of XML code and told you to copy it into your config file. After I followed their instructions, I really started everything. The person who wrote the handling of this exception could easily have left you a NullReferenceException or a ConfigurationException , but he did not. He knew that a large number of users would face this problem and knew the reason. The reason, relatively speaking, is that these users did not perform some action, because it was not obvious to them, because they didn’t open any tutorial - they just found the ready code and launched it. The developers, on the other hand, took care to get to it exactly at the moment of launch with the help of. Among developers, there is an interesting belief that UX is not their concern, that their business is to deal with backends, databases, APIs and other things. I do not agree with this. With any of your code, one way or another, will interact. If you are creating a database schema - know that someone will try to extract data from there. You write API - someone will use it for the application. You develop the application - someone will be responsible for his support while you are on vacation.

When we write code, we determine how interaction with various groups of our users (with fellow developers, customers, partners) will occur. It is very important to consider the experience and patterns of their work: what you learn will help you more intelligently develop your systems in the future. So, we will consider examples.

First day at work, company X

Imagine that you are a web developer and you have just been hired by a new team. And here you come to the office on Monday morning. They show you where the coffee machine is, where the fire exit is, then finally sit down at your desk and say that you, for a start, familiarize yourself with the site and launch it locally. So first you need a site code. You go to GitHub. Open a repository called "website", but it turns out to be empty. You see another website2 repository, open it, but it's empty here too. Then find “website2015”, think that probably everything is there - but no. Find another "website", but here are just a few Perl scripts. Then you politely refer to a colleague next to the question, where do you find the site code. It turns out that everything is stored in the "finance" repository. Why in "finance"? Because, as you explained, the site developer worked on a team of financiers ... Ok, you move on. Find the code, run it, but alas, nothing works: a lot of required dll-files are missing. You are again forced to turn to a colleague nearby - now about the dll-files. He quickly understands what you are saying, everything is OK, now he will connect you to his C drive and you will copy all the necessary files to yourself. Complex scheme, you think ... But anyway, you get all the necessary files in your hands. Shake start. But again the problem: there is no connection to the database. At best, you just continue all day to pull your colleague and then in the evening you still run the site on your car. If you are unlucky, then such an error will wait for you:

In fact, money was paid for this e-mail and for the text you see. This someone knew more about the nature of the error, but he decided that he wouldn’t tell you anything (he didn’t care), and you somehow figure it out yourself. Frankly speaking, the experience is not the best. Usually, good developers, after going through such torment, immediately take to document the process. They make up a small manual that describes the entire sequence of steps, attach the necessary files, explain what needs to be done to connect to the database, etc. But this kind of documentation, as a rule, becomes outdated very quickly: in a week someone will update one of the dll-files and your caring guide will instantly lose in price.

First day at work, company Y

You were also hired by a web developer. On Monday morning, you are in the office for the first time. The first thing you are assigned to: locally run the site, the code for which you will find in the Applejack repository. You go into GitHub, clone the repository, press F5 and see: “Restore NuGet packages”. Take note: the company is configured server NuGet; here they keep in common all dll-files so that nobody needs to ask them from a colleague nearby. The recovery is complete, but the launch fails: "Error connecting to the database." You go to the same repository and in the folder called “SQL” find all the database scripts. Let's stop and analyze. The tide of dopamine is definitely taking place. After all, you just coped with the task. At the same time you did not have to ask anyone for help - you yourself raised the system and launched it. Easily solving the problem, you also remembered how everything worked. You have easily fixed, for example, the fact that the repository has a separate folder in the database and that there is a description of the scheme. And when in a few days you need to figure out how this or that table of the database is arranged, you will easily restore the logic, find the file with the scheme - you will not have to ask anyone. The whole procedure of launching the site takes you no more than a couple of hours. After that, your colleague offers you to go for lunch. You go along with him for a hamburger and on the way ask why the repository with the site is called “Applejack”. He explains to you that all repositories here are called by the names of the characters "My Little Pony". After all, it does not matter how to call the code - the presence of the name is important. Therefore, they printed a list of the names of all the ponies from the cartoon and each time they create a new project, they simply choose a new one. It seems that this is nonsense. But it turns out that this approach is incredibly convenient. When the monitoring system sends you a notification saying that a problem has been found in the work of “Applejack” - you can be sure that you will immediately understand what code is in question. Using names is also very convenient when you are doing, say, a financial analysis and you need to get a picture of the distribution of resources for various projects. Programmers have the concept of a limited context, the idea of ​​partitioning the system into domains. Names help you get similar structures. “Applejack”, “Brandy Snap”, “Cherry Jubilee” - each of them appeals to his system, covers everything connected with it. In a day, you will no longer be amused by these names and you will feel how comfortable the system is.

UX: some history

This is what my first computer looked like:

It was the Intel 286, which was launched on the famous MS DOS diskettes. When you turned it on, he first made a whole series of sounds, after which it appeared on the screen:

You had a working computer in your hands. But then, so that you did not try to do it, most often he answered you the same way:

It was an expensive computer and, moreover, an impenetrable concrete wall. It was impossible to work with him: you endlessly saw “A>”, he swore at every command you entered. Therefore, you acquired a thick reference book and there you looked for the exact syntax of the command. Another popular PC at the time was a Macintosh running Mac OS 7. When you turned it on, a small icon of a smiling computer first appeared:

Then the “Welcome to Macintosh” sign lit up:

For some time the computer clicked and wailed, after which the download was completed and an interactive desktop appeared on the screen with a lot of the whole clickable:

At hand you had a mouse. You quickly mastered it and could easily control the cursor on the screen. You have gradually explored the desktop: “File” - obviously, you can manage the stored files here, “Edit” - edit, “View” - view. Mack embodies the idea of ​​Affordans (the idea of ​​opportunity) - when the system demonstrates what it can do. And instead of climbing into the directory, you can enjoy researching the system: choose from the offer, try the possibilities. Sometimes people abuse this approach. We have features, they say, so let's add a button for each of them in the interface - it will be convenient. They get something like this:

As you can see, there are countless buttons and a small window in the middle in which the user will write code. The bottom line is that such an interface is no better than DOS with its eternal "A>". Because it is insane to bring all existing functionality into buttons. The user will not know what to begin with, nor what this or that button is responsible for, or how to work with it all.

UX: the best

Speaking of UX, I always highly recommend watching this video:

I think that many have learned the first level of the game Portal 2. Not only is this funny and demanding - the authors taught you how to move, how to interact with the environment, and what keys to use for a minute. This is how your movement along the learning curve should be!

Customizable functionality

Another example I’ll mention is MS Edge, an alternative platform platform for Microsoft's web browser. Suppose you are a programmer and you have just installed MS Edge. You open any page, click on it with the right mouse button and for some reason you see only two options: “Select all” and “Print”. How do you think, I am a software engineer, where are all my tools for work? You enter the menu marked with three points and find the “F12 Developer Tools” here. Next time you will quickly find this option in the list: it is very noticeably marked by the hot F12 combination. You turn on this option and Edge writes to you: “Now the item“ Check element ”and“ View source ”will be shown in the context menu. Edge customization was well thought out by the developers. As for the source code, as you understand, 99% of all people using web browsers never open it. It’s hard to imagine that your mom is calling you, she says that the Internet has broken, that she opened the source code, but she forgot what to do next. The first thing you advise her is to close the source code. For the developer, this tool is very convenient: it allows you to solve some problems in the time of the order of 10-15 seconds. Thus, the default Edge does not load you with all its functionality. If you need this functionality, you can easily enable it.

Let's talk now about what we can bring to our own code in order to improve the experience and patterns of those who use it. I suppose that all of you are familiar with the idea of ​​code completion: you write the name of the object, put a period - and see a list of everything that is available for use.

You write Console.ForegroundColor , set the equal sign, and the system, realizing that you have applied to the listed type, offers you the available options:

The technology is called IntelliSense and greatly facilitates the work of the programmer. You do not need to refer to the directory - just put a point and choose from the existing one. We all use this feature, but how many people tried to embed it in their own code to help the people who use it? Recently, I realized that, despite 15 years of working with .NET, I still can’t compose SQL connection strings: I just don’t remember their syntax. When declaring a new SQLConnection, I’m prompted to insert a string, but they don’t say anything about how to construct it.

I have to go to ConnectionString.com and look for information there. As a solution, I created my own small SQL.Connect library. In it, I put a single class, I defined a static method in it, and in a comment to the method I put a piece from the documentation. Now, at the moment when you need to specify the connection string, I get a hint with the syntax. Problem solved. Implementing such a solution is very simple: you literally need to insert a piece of XML data into the method documentation (a special kind of comment).

If you use Visual Studio, Visual Studio Mac, Code Writer, or any other environment that supports user documentation, your comment will be recognized and will appear in a pop-up window as a hint as soon as you open the bracket.

In this case, you do not have to stop, switch to the browser window, google the syntax. Write the code will be much more convenient. But it is important to note that such solutions work well only when you know exactly what the user will do and how. Sometimes the script of the target user with your class library is strict, without branches. But if everything is not so simple, then we should take care to help the user, suggest which options are currently available to him, offer a convenient interface for selection.

Signposting

There is a pattern in UX called “signposting” (literally: “road signs”). Suppose you know that within the framework of working with your application, the user is at some crossroads, changes some code, etc. What can we do to tell him the available options and resources? Let's talk about the HTTP API, which is one of the best implementations of the signposting idea today. Why are we so easy to use web pages? Because they are full of links, which are the most powerful navigation tools. The links you see on the page show you where you can go. Click on the link - go to another page; did not like the page - click “back”, find another link, click on it - go to a new page. The network is so conveniently investigated by the system precisely because of the competent "signposting". These patterns are quite possible to borrow for our API. Over the past year, my team and I have been working on a project that was originally conceived as a REST API with Hypermedia built into its resources. We received some JSON code and, using HAL (Hypermedia Application Language), inserted links into it that would point to resources available from the page. At some point, we needed to create several tools that would help us explore and debug the written code, which we did. Subsequently, we decided that we would publish these tools along with the documentation on our API, so that our users could also use them if necessary. One of these applications looks like this:

In theory, anyone with the necessary rights can log into it, switch to sandbox mode, and then see the executable code of the main application. The links inside the JSON-code can be clicked and thus navigate through different pages.

Thus, in order to explore our API, developers will not need to write their programs, view the documentation - they will be able to explore the system, reviewing it and interacting with it. We began with the fact that we created support for clicks, navigation, and moving from one resource to another. We later added tools to interact with Hypermedia. Now you can select a resource, display it in the browser and execute a PATCH, POST, PUT, DELETE request right from there. Such decisions, again, eliminate the need for documentation. You will refer to it rather as an engineering specification (when you need information about the code table used for a particular field, etc.). If you just explore the system, you want to get an idea of ​​how it works, to be able to implement your own solution on top of it - then I like the idea of ​​simply putting it on the open Internet so that people can play with it as they please.

For the most part, we talked about our interaction with other developers. But there is another numerous category of people who will work with our code - those who are engaged in supporting the system. These are engineers who advise clients by telephone, the team of your back office, the operational teams of the companies to which you deliver your product, etc. ... Therefore, I will devote the rest of the conversation to monitoring and logging.

Monitoring

Scenario one

Morning, you sit at work. The bell rings. The person at the end of the tube immediately declares: "you have a problem with the system!". Wow accusation! You listen, take some rather useless notes, ask for contacts and hang up. And you are: "Is there a problem with the system? What does he mean at all?" The next call is heard, and there too: "you have a problem with the system". You are: "What system at least?", Client: "With the one on the Internet! It does not work!". People continue and continue to call, but can not explain anything useful.

Time passes, and finally someone promises to send you a screenshot. You cheered up, the screen should facilitate your work! But what they send you looks like this:

What are your chances of fixing this problem? The application code base has approximately 60,000 lines of code, and probably about 5,000 HTTP requests. It will take 20 minutes to check each request - so why should you spend 6 weeks on one error? All that you know: "The request has timed out." , , , . , . 5000 . , . : .

. , . , .

, . . .

, , Intranet CDN. , — . : . . , Intranet , CDN. CDN. , . : , . , . . , , , . . . — . ? , - , , . , , , , . . . , .

, , . , , - — . , — .

, - , . NASA, -5, , 6 000 000 , 99.9% . , 6000 . . , , -, . - , . , , : , .

. , — . 6 , . , , . «».

«», , , , . ; , , , , — . : , , . . , , , .

Nancy

API, , Nancy — HTTP API .NET.

-, URI «/_Nancy/» , , .

. , Visual Studio — , , , . , . Nancy , . , , - . , - , - . . ( ). , , - 30 — (, , . .). . . , , , . . — . — .

. , 100%.

. . , 100%:

1․ .

2․ :

, . . . . , , , , — .

3․ :

. , , . , . - , , , . , — 5 ?

, , , , . , . , , — .

Redgate

, SQL- Redgate.

24 . , 10 , , , 6 . , : , , ? Redgate . . , , , ( , . .). , . , , , , . , . , Amazon, , .

— , , , , . .NET 5 : FATAL , ERROR , WARN , INFO DEBUG . : . , . . , . : Graphite, Splunk, Logstash .; SaaS, Graylog, Logit.io. . , , -: - INFO 10 , FATAL , . , - , , , , , . .

FATAL

: , , . , . , . , , , FATAL . FATAL . , , .

ERROR WARN

: API, . ERROR — , - , , (, ). WARN — , . API , , , 10 . , API , - .

INFO

: , . , : , , . , , . INFO . , , . . , , , . — .

DEBUG

, : Console.WriteLine — , Log4net, NLog Serilog . ( ). , , - .

DEBUG : , , , . . , , — 3 . , , , , , , — . .

?

, , , — , . , . :

: «»

1. Names «Applejack», «My Little Pony». , , — . , .
2. . . ( , ) ( , ). (). ASP.NET WebForms: . - — , . , , — .
3. «Signposting». : , . , , - — fluent interface, . , «Database» : «Encryption», «Credentials», «Timeout» . . , .
4. Transparency. , . , , . , . , .

, : , user experience. — - . , , , . . .