Volodymyr Obrizan: personal website - 07

I like reading documentation

2026-08-07T16:02:50+03:00

I read documentation this week. And last week too. And next week I'll be reading documentation too. I like reading documentation.

Why should I spend time writing to AI, waiting for "thinking longer for the better answer"™, when I can just Google the documentation I need, open it, and enjoy a leisurely read from beginning to end? Bear in mind: AI can't reproduce copyrighted material word for word — it has to paraphrase it. So why read text paraphrased by AI when you can read the actual original source?

The Education Crisis

2018-03-07T10:04:00+02:00

It hurts me a lot to watch the education crisis in our country. I experience it as a personal tragedy. What made me write this note was an incident that happened in one of the programming-related chats.

One day, a chat participant posted a photo of the theoretical problems he had been given at an interview. Among the other problems and questions were these: “How many bits are in a byte? Convert a number from decimal to hexadecimal. Count the number of bits in a number.” I was surprised by the reaction from beginner programmers:

— Ha ha ha! Where in real projects do you need to count the number of bits in a byte?
— Pffft... What kind of idiotic assignments are these, why would a frontend developer need this?

The drama unfolded the very next day. One of the chat participants asked for help with this problem:

— Save me! Help! I’m adding 0.1 and 0.2, and the result I get is not 0.3 but 0.30000000000000004!

The very people who had mocked the assignments about bits in a byte just yesterday tripped over their own ignorance today, and over their unwillingness to study the fundamental basics of how computers work.

Modern computers are discrete. Numbers are stored as integers and real numbers. Real numbers are stored in fixed-point format or in floating-point format. The main feature is that the weight of each digit is a multiple of two. For integers, that’s 2⁰, 2¹, 2², 2³, and so on. And for fractions it’s the same thing, but in the denominator: 2⁻¹, 2⁻², 2⁻³, and so on. That is, 0.5, 0.25, 0.125, and so on. If we allocate two binary digits for the fractional part, then we can represent numbers that are multiples of 0.25: 0, 0.25, 0.5, 0.75, 1, and so on. But with that kind of digit grid, you can’t represent 0.2, or 0.1, or 0.3.

And how many other courses and disciplines are ignored by today’s community of programmers? Discrete mathematics, algebra, higher mathematics, graph theory, probability theory, statistics, data structures and algorithms, object-oriented programming, database management systems, systems engineering, information and coding theory, mathematical modeling, and so on, all the way through a full four years of a bachelor’s degree.

The geopolitical crisis led to an economic crisis. The economic one led to a cultural one. The cultural one led to an education crisis. The education crisis led to a professional one. The professional one is leading to an industrial crisis.

Revelations from God and Programmers

2017-04-07T23:27:00+03:00

Programmers adore Revelations from God. That’s when some truth is obvious to everyone, while programmers arrive at it through long, expansive reasoning.

Today I read the article "TDD Harms Architecture". (http://blog.cleancoder.com/uncle-bob/2017/03/03/TDD-Harms-Architecture.html). The article is about how, supposedly, the culture of automated testing harms a program’s architecture. After long, expansive reasoning, the author ends with five paragraphs of text about how it’s programmers who make bad architecture, not tests.

Another programmer has delivered Revelations from God. To me this is just as funny as the label on a Superman costume: "Does not grant the ability to fly."

A Joke for Project Managers

2016-10-07T00:18:00+03:00

Let me tell you a joke. Five programmers are sitting at work late on a Sunday evening, December 31, wondering: how the fuck did they end up there. "What did we do wrong? Where did we screw up? What didn’t we do?" Looking for someone to blame and all that bullshit. And suddenly one says:

— Wait... When we were planning the project, we were just sitting around telling fucking jokes.

Personal Effectiveness: a Task List

2016-02-07T23:00:00+02:00

People often ask: how I personally organize my work. I use a lot of tools for personal effectiveness. Today let’s talk about the task list.

A task list is the most important tool for organizing personal effectiveness. Absolutely everything that needs to be done gets offloaded from your head into the task list. The list is divided into “projects,” for example: “Work,” “University,” “Home,” and so on. Tasks are also divided into “Do today,” “Do this week,” and “Do later.”

The most important condition is to offload absolutely everything that’s in your head. From elementary things to complicated ones. You must not give in to the temptation of “nah, I’ll remember this and do it anyway.” In 95% of cases, things like that get forgotten and don’t get done.

For managing tasks, I recommend “Micromiles”: http://micromiles.co/

The task list for the day and for the week needs to be reviewed daily, moving tasks around if necessary. The task list for the week and for later needs to be reviewed once a week and also moved around if needed.

As a result, your head will be completely freed from the need to remember what has to be done, and all your attention will be devoted only to the tasks that need to be done today. With a task list, it’s impossible to forget something. You can consciously not do it, but forget it — impossible.

I remember when I first wrote all the tasks from my head into the program, I felt an unprecedented relief. It turned out that yes, there were a lot of important tasks, but for that particular day there were literally two, and I had already taken care of both of them, so there was no need to worry anymore. It was happiness.

For more detail on the method of getting things to the finish line, you can watch Maxim Dorofeev: http://mnogosdelal.ru/slidecasts/dovedenie-del-do-kontsa/

How people live without a task list, I do not know. I strongly recommend starting one.

Devalued Values

2014-09-07T01:38:00+03:00

In the summer of 2004, a close friend (Sasha, hi!) invited me to go to an evening sermon at a Kingdom Hall of Jehovah’s Witnesses. What could possibly interest me in a close friend’s invitation to go to an evening sermon at a Kingdom Hall of Jehovah’s Witnesses? The fact that the preacher was from the United States, and American preachers know how to speak interestingly and convincingly, and besides, I wanted to hear a native speaker of my second native language. The sermon lasted about 40–50 minutes; I remember almost nothing except the title: “Devalued Values,” and the idea reflected in that title. The point was roughly this: the Lord God created commandments that we must follow. Some people decide that certain commandments should be followed and certain commandments need not be, and in this way they devalue God’s covenants.

And I remembered this gesture of the preacher’s: with his right hand he drew a line in the air parallel to the ground at head level and said, “This is how God wants to see you.” And with his left hand he drew a line at chest level and said, “And this is how you want to see yourselves. You have devalued the values.” At the time it struck me as merely amusing, nothing more. But a few years later I encountered devalued values in the field of education.

What is a value in education? The knowledge acquired. What we are now seeing at the university: students are unilaterally lowering academic standards. Let me say right away that by a standard I mean excellent knowledge of the subject: 90–100 points. Besides academic standards, there are also professional standards in the labor market; they are, of course, higher than academic standards, but since they are directly proportional, when one standard is lowered, the other is lowered as well.

During the Renaissance, the amount of knowledge (and therefore the standards) increased. Recall Isaac Newton’s immortal line: “If I have seen further, it is only because I stood on the shoulders of giants.” What is meant here is that, on the basis of the knowledge of previous generations, it became possible to obtain new knowledge and pass it on to descendants. Now the opposite process is taking place: some students independently lower the standard of knowledge to a mediocre level. Some students simply try to pass the course on time, in some half-assed way. This has to do with the fact that the exam period is planned in advance, time is limited, and knowledge is not exactly some great value. And if there is one night left before the exam, and the exam date cannot be moved, then the remaining free parameter is the quality (amount) of knowledge. Naturally, such knowledge will fly out of their heads faster than the instructor can close the grade book after the exam.

Several characteristic thresholds can be identified:

— 60 points — the passing score; any less is not allowed, it will already be a “two,” and they won’t move you on to the next semester;
— 75 points — the average score needed to receive a scholarship.

A similar situation arises with courses that do not have an exam but have a pass/fail credit instead — there it is enough to get a “three” to move on further.

And this degradation is observed in every generation of students. In my nightmares I see the students’ knowledge at one moment turn into a material point, and in the next moment disappear altogether.

The KhNURE Website Continues to Amaze

2014-06-07T11:16:00+03:00

On August 5, 2012, I wrote a note, "The KhNURE Website, 20x2".

In 2013, they did finally change the site’s design. But the editorial policy stayed the same.

Thanks for the invitation, but alas, not everyone has a time machine.

Total Recall

2014-02-07T00:22:00+02:00

As late as noon on Thursday, nothing foretold disaster. But at 4:00 p.m. the first warning bell rang from an unknown number:

— Hey, so are you coming tomorrow?

After a couple seconds of thinking, from the voice and the question I figured out who was calling.

— Yes, of course I’m coming, as usual. Did you change your number or something?
— No.
— Weird, it didn’t show up for me.

The second warning bell rang later, a few hours after that, when in “Viber” instead of first and last names it was just showing phone numbers.

No need to go ask Steve Jobs here — my phone book had crapped out.

649 contacts that had been accumulated over 10 years, the phone numbers of people I had called or who had called me at least once — all vanished in some unknown direction. And then an even sadder fact was confirmed: it wasn’t just the contacts that were gone, but all the data tied to iCloud — Apple’s cloud platform. For example, this is what the list of notes looks like, where I collect various thoughts, ideas, and useful links:

The calendar was empty too. The to-do list was virginally clean.

I got curious how many phone numbers I remembered even without the address book. I counted five, three of which turned out to be useless: my work phone, the phone at the department, and the MKS phone number.

Then another thought came to mind: maybe I shouldn’t bother restoring the phone book? Maybe I don’t need those 649 numbers? Who are all these people? Maybe whoever needs me will call or send a text themselves?

The last thought was that I actually don’t care how many numbers are in the phone book: well, zero is zero.

And in the evening I rebooted the phone, it huffed and puffed for a minute, downloaded all the data from the cloud, and everything fell back into place.

Death — Symbolic

2011-10-07T09:29:00+03:00

Chuck Schuldiner — the silver voice of death metal.

Death — Symbolic on Yandex.Music

News from Civilized Europe

2010-11-07T08:59:00+02:00

A correspondent from Prague reports:

As of January 1, citizens of the Czech Republic are allowed to have on them: up to 15 grams of marijuana, up to four ecstasy tablets, two grams of amphetamine, one and a half grams of heroin, one gram of cocaine. They are also allowed to grow at home up to five cannabis plants and 40 hallucinogenic mushrooms. Criminal punishment for possession of the above-stated quantity of narcotic substances has been abolished.

Drugs Legalized in the Czech Republic

I think the next step will be selling drugs in supermarkets, as well as in school cafeterias. Drugs will also be available on credit, and social programs will appear for distributing drugs to the poor. Journalists don’t write about the fact that heroin and cocaine are addictive.

On Design in Developer Documentation

2010-08-07T18:39:00+03:00

For a long time I couldn’t figure out what the problem was, but I’ve just sorted it out and am hurrying to report back to you. I noticed that when I read documentation in MSDN, my soul somehow feels good and calm, and when I read it in doxygen, I feel kind of nauseous.

No one will argue that documentation is very important, especially when you need to get to grips with a new large project. And the quality of the documentation matters a lot too: how it is put together and presented to the reader. It’s not a simple thing; it seems hard to measure. Although you could take a group of people, give them the task of finding a list of facts in documentation with different designs, and measure the time spent reading, searching for information.

So, if I’m interested in some class from the .NET library, then in MSDN the description looks like this:

Here you can clearly see: the “constructors” section — one method, the “methods” section — five. The density of information presentation is equal to six units. Let’s look at the documentation in doxygen’s default style:

The sections are still visible, but it’s no longer as easy to count individual methods. Visually, the thick blue links dominate the method declarations and distract the eye. What’s more, on one screen we see the description of only three methods. So the notional density is three.

Notice how doxygen thoughtfully made the type “unsigned” into a link. If you forget what unsigned is, you can always follow the link and find out.

An important part of documentation is not only the description, but also source-code examples. In MSDN, we see source code formatted like this:

One, two, three, four — and that’s it. Four colors. Source code in doxygen looks like this:

Here, though, we see these highlighting classes: 1) directives; 2) links; 3) keywords one; 4) keywords two; 5) comments; 6) built-in types; 7) identifiers, punctuation. Seven different colors in total. Of course, highlighting is a matter of taste, but if the user already knows that you can click any identifier and go to the place where it’s defined, then why highlight links in blue one more time?

And finally, a collaboration diagram from doxygen, reduced by a factor of five. Is anyone really going to use it at its real size (3600 by 1500 pixels, view original)?

Links to manuals and personal experience with maintaining documentation, configuring doxygen, and so on are welcome in the comments.