DEV Community: Ilia Menshikov

Documenting agreements

Ilia Menshikov — Fri, 10 Feb 2023 12:42:22 +0000

Agreements are an essential part of software development. They lower development costs and make developers' lives easier. But there is a problem - they often complicate things because they aren't properly documented and conveyed across the team by word of mouth, like old fairy tales. While spreading, agreements change. Suddenly, new details appear, and old ones are gone. By the end, every team member has their own agreement picture in the head, and even that picture sometimes fades away.

Even worse - when teams start documenting these agreements, they do it haphazardly and often create a mess of loosely coupled documents, half of which are not even up-to-date.

In this article, I'll tell you the right way of documenting agreements, so they will help you.

So, how can we make agreements helpful? We not only have to document them but also do it so that:

they were easy to use;
following these agreements required minimal effort;
it would be easy to understand if these agreements are still valid;
it would be easy to understand why these agreements even exist;
ideally - they were automated.

One can come up with lots of ways to classify agreements. I will split them by their abstraction level:

code-level agreements;
architecture-level agreements;
processes-level agreements.

Agreements on different levels require different ways to document them and bring different benefits. Let's take a look at each level.

Code-level conventions

The aim of these agreements is to make code uniform, comprehensive, and readable. Here are some examples:

We use double quotes instead of single ones.
We don't call ENV directly from the code except in the Config class, where we wrap these calls into methods.
Service objects have postfix Service and one public method call.

These types of agreements are created to lower the reader's cognitive load and help him become used to unknown code faster. Like Martin said, code is read up to 10 times more than written. Despite your opinion on the Ruby on Rails framework - it has an incredible convention over configuration principle at its core, which allows any Rails developer to open someone else's project and immediately navigate it pretty well.

So how to document these conventions? Linter tool! If there is no suitable linter rule, write your own lint. Almost every linter allows you to do that: here is an example in Go language, and here is for Ruby.

Using linter for such conventions brings you three benefits:

There is no need for a developer to think about them - linter will highlight every error and often even fix them for you.
If you use code reviews in your team - you free your reviewers from thinking about these things and give them more time to look at more important things.
The developer will see a problem at the very start of the development cycle, so he will fix it immediately without spending time to return to the context later. It becomes cheaper to keep the agreement.

One more bonus: writing a new linter rule is excellent training for a junior developer. While completing this task, he will learn a lot about code parsing and building AST and understand language more deeply.

Architecture-level conventions

This is a higher-level type of agreement that aims to make your architecture thoughtful, coherent, and uniform. A few examples:

We use the Python to write regular services and Elixir in the highloaded parts of the system.
The backend returns errors in described format.
Each service is required to send metrics in prometheus, on the /metrics endpoint, the port for sending metrics is configured by the PROMETHEUS_PORT environment variable.

Such agreements not only reduce cognitive load, but also solve three more problems:

Reduce operating costs. If the services are launched in the same way, with same logs format, publishing the same metrics, then it is much easier to maintain the service and cope with incidents.
Reduce design costs. The developer doesn't need to design the architecture from scratch every time - you thought in advance, and now he needs to design only a specific feature or service, without worrying about basic things.
Reduce communication costs. If the server's response or event format in Kafka is predetermined, developers don't need to discuss their interaction each time, instead they can simply refer to the convention.

Such agreements are more complex, and I prefer to fix them in two steps.

Step 1 - Describe

Architecture Decision Record (ADR) is a tool for documenting such agreements. Its charm is that it captures meta information along with an agreement: why such an agreement was adopted; what alternatives were discussed; when it was last revised; is the agreement still valid?

This allows the new team member to understand the reasons for the decisions made and not ask people around about it.

ADR consists of several main blocks:

What problem does the agreement solve?
What options for solving the problem were considered, and what were their pros and cons?
Which option was chosen in the end?

There may be additional blocks - for example, implementation costs calculation.

It's more convenient to keep ADR in a system where one can see the history of changes and discussions. My choice is Github and Notion, each with its pros and cons. The advantage of Github is that it has a review tool and version history out of the box. Notion can be a good solution due to the convenience of working with databases and tags. And also - non-developers can easily handle it.

If you want to get started with ADR, I recommend looking at the repository, where you can find different ADR templates and examples of how to use them.

Step 2 - Automate

ADRs are more challenging to automate than code-level conventions: design linters have yet to be invented (what a pity!). Nevertheless, it is possible to partially automate them, depending on what kind of agreement it is.

Create and update service templates for agreements on languages, libraries, and embedding services into infrastructure. Then the developer won't write new services from scratch but rather copy it from the template and immediately receive the configured Dockerfile, metrics publishing, etc.

Similarly, you can create class generators within one application. Suppose you had agreed on several application layers (controller => form => service object). In that case, you can make a simple console command that will generate all layers for a new feature at once.

If you have agreed on some principles that cannot be automated in this way, you can organize checklists that are automatically added to a merge request or a task in the tracker; thus, the developer can quickly go through them before passing the task on.

Processes-level agreements

There are many agreements for processes in each company, for example:

Description of how hiring in the company works.
Description of the release rollout process.
Requirement for design reviews for large tasks.
Conducting a team meeting twice a week with a discussion of current tasks and obstacles.

Until recently, I did not think about documenting these agreements, although they significantly affect the company's success. Documentation of these agreements not only carries benefits of the types mentioned above but also allows you to rationalize the processes, transfer them to the visible plane and think about their expediency.

I got the idea from Vitaly Sharovatov. He proposed a tool similar to ADR - Process Decision Record (PDR). The only difference is that instead of architectural decisions, it describes decisions about processes. In addition, he suggested putting a "rethink date" in each PDR - a date when you return to the document to see if it still solves your problems in the best way, n months after adoption (by the way, the same can be done with ADRs ).

As for automation, there is little you can do. You can automate some processes by setting up a workflow in Jira, setting reminders for meetings, or creating a bot that automatically prepares a presentation of the week's results (I did this, though, in a foreign company).

But often, you can't really automate processes, and your main goal is to make them easier to follow than not follow. Nevertheless, documenting agreements will still be helpful, even if your processes are already easy to follow - formalization and rationalization will allow you to improve them.

So, what's the result?

Documentation and subsequent automation are beneficial: time spent on development decreases, applications become more supportable, and processes become smarter.

One could think that all this is unnecessary bureaucracy because "we are good guys - we can develop code without it." But in fact, agreements will save you substantial amounts of time and money and protect employees' nervous cells. Sure, you don't need to deal in absolute and reject anything that goes against agreements - this may be a sign that the agreement needs to be updated or that you didn't initially think about some of its aspects.

If you haven't yet started documenting agreements in your team, move from lower abstraction levels to higher ones: start from code-level agreements, then architecture-level, and only then cope with the processes-level. Agreements documentation is a habit to develop in your team, and starting with less abstract concepts is much easier.

In addition, not all types are described in the article. For example, you can document the design agreement as library components.

Each new type of agreement goes through the same three stages:

Figure out how to document it.
Figure out how to automate it.
As time passes, ensure it saves more resources than it takes to keep it.

And the last one. During the documentation process, it may be found that some of the existing agreements are apparently, not justified by anything, waste your team's time, and are generally harmful, but you are already used to them. In this case, you have to overcome the habit barrier in the team's minds and convince your team that the rejection of agreements is sometimes more important than accepting them. But that's an entirely different story.

Why Developers Should Own the Product and How it Will Make Them Happy

Ilia Menshikov — Sat, 04 Feb 2023 16:41:00 +0000

I have been working as a software engineer for ten years. I managed to work in different companies: product-based and outsource, large and small. For the last three years, I have also been a manager — I manage a team of developers and help them develop and hire new people.

I’ve noticed that developers often think of their job as “writing code”, “adding features”, or even “closing tasks in Jira”. I used to think the same way. Today, I will explain why this approach limits growth and, more importantly, happiness.

The mindset

So what does “ownership” mean? In my opinion, every developer should remember that he is a part of:

a business,
a product.

Accordingly, the developer’s task is to help the business grow and improve the product. It implies that the developer must:

know the product and its subject area;
know the product’s users;
understand how the business works;
understand product metrics;
know the direction the product and business are taking;
understand what other departments in the company are doing.

Collectively, this is called product thinking. Together with personal interest, proactivity, and most importantly, responsibility for successes and failures, it makes up the concept of “ownership” of the product.

This approach requires significant personal effort. Why would a business go for it, and why would you?

Benefits for the business

A company benefits from having product-minded developers in many ways. I’ll name the main ones.

Getting Things Done

If a developer considers his only task to be writing code, he abandons the task as soon as it leaves his area of responsibility. Then tasks often return from testing because the developer did not really check the result. Then the branch with the code freezes and does not get in production. People forget to roll out the experiments or to turn on feature toggles.

Such problems can and should be fixed by changing processes, but when the developer owns the product, he doesn’t consider the task completed until it is in production. Therefore, he checks everything carefully, ensures it’s in production, and checks if everything is set up, configured, and rolled out.

Choosing the right software architecture

A developer that knows the domain, the product, and its users can make better design decisions by predicting possible future changes and the consequences of his choices.

Higher Efficiency and Creativity

Employees work better this way, an explanation later in the article.

Proactivity

This is the most crucial point. A developer who feels like he owns the product does not wait for instructions but is proactive. They warn about risks in advance, correct mistakes, and come up with suggestions.

To summarize: the company gets a more efficient and responsible employee, whose decisions turn out to be correct more often. Isn’t it amazing?

What’s in it for you?

You will be more valuable to the business

I described above why you become more valuable to the company. Good employers notice this — you get more freedom, more opportunities, and in the end — more money and stocks.

The most successful developers who grow in this direction eventually move to a stage where a hypothetical James Brown no longer gets invited to the position of a developer. He is invited to the role of James Brown! The company hires him as a person who makes business better no matter what he’s doing.

You will work in the best companies

The skill of product ownership will force you to choose those jobs where you can apply it. In such companies, you will get more freedom, grow much faster, and develop different abilities, and great like-minded specialists will surround you. The last point is essential and often underestimated — our environment shapes us. You become more active and professional in the company of enthusiastic, energetic, professional people.

Let’s talk about happiness

The last advantage I’ll talk about is, in my opinion, the most important. So I will pay a little more attention to it.

Why do we even live? Many generations of philosophers have been trying to answer this question, so that I will leave the task to them. Instead, I propose to think about how we live.

Look, there are 24 hours in a day, of which 8 (ideally) we sleep. There are 16 hours left, of which work takes up half. If we take into account our other activities: commuting, shopping, working out, meeting with friends, etc., it turns out that we spend more time at work than with our family. As a rule, we treat a spouse’s choice very responsibly: we don’t get married just like that. We live together to be happy. Why do we talk so little about happiness at work if we spend so much time there? Why do we stay for years in dull jobs, doing uninspiring things?

Can’t we make it better?

I think we can, and the key is in owning the product. There are several points from which you can see the connection between happiness and owning your product.

Ownership and Alienation

The reflections on alienation first appeared in the works of John Locke, then developed and became a full-fledged theory in Hegel’s and Feuerbach’s works. Marx, on the other hand, transferred this problem from a religious perspective into a common one. I will not bother you with a lengthy analysis of these philosophers’ thoughts and will give you the main ideas relevant to today’s article.

Marx wrote extensively about alienation — the separation of the worker from the results of his labor and the very process of production. A person works but does not feel any connection to the final product: every day he screws the same bolt on the conveyor and doesn’t feel that he is creating something big, because his part is so small and monotonous. The worker doesn’t see the point in the work — all his activities come down to just turning one bolt. Moreover, the worker doesn’t use the product he creates because he can’t afford it.

The economic part of the problem affects us to a lesser extent: today we earn quite a lot compared to a worker in a factory (albeit less than a factory owner). But the psychological part is very relevant: developers often lose the meaningof their work. Their actions at work seem meaningless to them, they feel unnecessary, and they live an unhappy life. If your job is to complete a flow of tasks in Jira, if you don’t know why you perform this or that task, if every new day at work is the same as the previous one, are you that different from the factory worker?

Developing a sense of product ownership will allow you to cope with the psychological part of alienation from your work. Choosing a company that offers equity will also help with the socioeconomic one.

The value of your product

We have an interesting cognitive bias in our heads called the IKEA effect. The fact is that we value things much more if we had a hand in creating them. People are willing to pay more for a cupboard they build themselves, and cake mix sales go up if you have to add a real egg yourself.

The feeling of belonging and ownership of the product will make you appreciate it more, be proud of it, and therefore feel the importance and see the meaning of your work.

Motivation and types of people

Modern business often relies on carrots and sticks, although research shows these methods are unsuitable for creative work. People who feel competent, autonomous, and connected to each other work much more efficiently. They are also happier.

At the same time, there are differences between people; what Daniel Pink called Type X and Type I. Type X are people for whom extrinsic motivation is paramount: how much money they will earn and what rewards they will receive. People of Type I are primarily interested in internal motivation — satisfaction from work done. It doesn’t mean that Type I works “for food”, it means that after the basic needs are covered, money and fame cease to be their primary incentive.

Type X is predisposed to “type A behavior” — the desire to achieve constantly and a tendency to compete. Type I tends to “type B behavior” — a calm and deliberate life.

Where am I going with this? Research shows that both types of people perform equally well. But people with Type A behavior are more stressed, more often unhappy, and they’re also much more likely to die from heart disease:

No significant differences were found between Type A and B agents and three measures of sales performance and one measure of general job satisfaction. Type A behavior among the sample was associated with measures of stress and number of health complaints.
— Matteson M. Matteson, Michael T., John M. Ivancevich, and Samuel V. Smith. “Relation of Type A behavior to performance and satisfaction among sales personnel.” Journal of Vocational Behavior 25.2 (1984): 203–214.

Results revealed that JAS-defined Type A’s and Type B’s did not differ in their attributions for success, but Type A’s made more internal attributions for failure than did Type Bs. This attributional difference was due to the Type A’s tendency to attribute failure to a lack of ability.
— Musante, Linda, James M. MacDougall, and Theodore M. Dembroski. “The Type A behavior pattern and attributions for success and failure.” Personality and Social Psychology Bulletin 10.4 (1984): 544–553.

Product ownership will allow you to:

feel more competent because you not only know how to write code but also understand why to write it;
get more autonomy because you are less tied to the person who sets your tasks. You will make many more decisions on your own if you understand what you’re doing and why;
strengthen communication with other people because now the rest of the employees around you — sales, marketing, product managers, and support team are no longer strange people who ask for odd things. Now you know why they want the changes and speak the same language as them.

A sense of competence, greater autonomy, and a better understanding of the other people in the company will change your motivation and behavior towards Types I and B, respectively, and thus make your life calmer and happier. And at the same time, maybe save you from an early death.

Conclusions

What is the result? Focusing on product ownership will make you a more valuable professional and, most importantly, a happier person.

The manager should think about building a culture in the team that will not interfere with product ownership, or, even better, helps the team develop this feeling in themselves. So your developers will work better. And die less often :)

I will also note that when you own the product literally (by owning equity), it is much easier to feel involved. So, it would be best if you choose companies that are partially or wholly owned by employees. If you have founded your own company, consider sharing a part of it with the team: research and practice show that this path leads to success.

Be happy!