Weekly blog posts about creative work in the tech industry

Previous page

Page 2 of 7

Working Software over Comprehensive Documentation

Dec 16, 2018

Two months ago I got interested in the four agile software development values. I have never disagreed with the values but I also haven't really reflected about them on a deeper level. Previously I have written about the first value of "Individuals and interactions over processes and tools." This week I'm discussing the second value, "Working software over comprehensive documentation."

We probably all hate writing documentation. But instead of bad-mouthing docs, I want to start out by pointing out the value of good documentation. The second agile value doesn't state that comprehensive documentation is useless. It just states that working software has more significance than comprehensive documentation.

Comprehensive documentation has two key benefits to any organization or team: it externalizes knowledge and it builds up shared understanding. When we externalize knowledge we take the internal knowledge of individuals and articulate it to a shareable form. When we build shared understanding we build shared vocabulary and common ground.

While documentation is a great tool for knowledge sharing, it's also time-consuming to produce and difficult to make it digestible. In addition to this, maintaining massive amounts of documentation is an enormous task. Especially when you are adding new features to your software every week.

None of us want software teams that spend the majority of their time writing and maintaining documentation. We want teams that iterate and move forward.

So what do you do? First, don't write documentation for its own sake. Write down the stuff that really matters and that is easy to communicate as written docs. Second, you can externalize knowledge and build shared understanding through other means than documentation. You can supplement your minimum viable documentation with different practices. Let me go through some examples of this.

When I'm onboarded to an existing project and try to understand how different features work, I start out by reading the integration tests for those features (integration tests combine different units of the software and go through different use cases). Sometimes the purpose of documentation is to describe how a system works. Easy-to-read tests achieve this same goal. Also, unlike documentation, tests stay up-to-date even when the development team's velocity is high (developers are forced to keep their tests passing and therefore rewrite tests when necessary).

Comprehensive documentation for a development team can also help them to reduce ambiguity and increase the consistency of their work. However, if you are able to adopt known systems and ways of working for your team, you don't necessarily have to write your own documentation–the documentation is written for you! For example, if you and your team decides to adopt git flow or trunk-based development as your development style, you can take advantage of the existing and public documentation for those systems.

The last example deals with the issue of knowledge sharing between technical and non-technical people inside a software project. Documentation can make it easier for people with different backgrounds and skill sets to find a shared vocabulary. But so can face-to-face discussions around artifacts such as post-its, wireframes, and demos. In fact, these discussions can achieve something truly important that documentation can't: they can uncover misconceptions and conflicts. Sure, interactions don't scale the same way as documentation scales, and discussions around misconceptions and conflicts can be uncomfortable. However, if you aren't right now dealing with a scalability problem, you can keep knowledge sharing as a more personal, non-scaling activity.

Final notes

Documentation by itself has no meaning. The meaning comes from the valuable knowledge that gets distributed to different people. Is your team documenting things? If not, what are the ways you are building shared understanding or keeping your work consistent?

Takeaways from Slush 2018

Dec 8, 2018

This week I attended Slush (startup and tech conference with over 20,000 visitors). Here are my three key takeaways about process, randomness, and trust.

Process and product development

During an onstage discussion about product management and design between Bradley Horowitz (entrepreneur and Google VP) and Irene Au (design partner at Khosla Ventures), Horowitz mentioned how excellent products are often results of excellent processes.

I got the opportunity to ask Horowitz what makes a good product development process become an excellent one. For some time now, I've been trying to wrap my mind around the meaning of process inside design and development teams. I do believe a great process can elevate a team to the next level. However, at the same time I'm cautious about processes that stifle individual and team autonomy.

Horowitz replied to me and the audience by saying that he is allergic to process. He sees the bureaucracy that process builds up within an organization, and given the opportunity, Horowitz will try his best to bust out that bureaucracy.

Horowitz also wants to remind us that the details of an excellent process vary from product to product and organization to organization. You don't build a physical product the same way you build a software product. A company of five people operates in a different way than a company of five thousand people.

Embrace the fact that there is no one right way of doing things. But remember, as Horowitz says, all great processes remove friction–whether that friction is ambiguity or bureaucracy.

Random success

You could say that Horowitz's and Au's talk was premised on the belief that product success is a result of premeditated actions of teams and individuals. In other words, you make your own luck.

This is not the story of Slack. During a Q&A session, Cal Henderson (Slack's co-founder and CTO) explained how Slack became to be the quintessential unicorn startup company.

Before Slack, the founding team was a struggling computer game company. They worked together on their ill-fated online game for almost four years. Henderson says that it was a failure from the team's side to work on the game for so long. After the first two years, it was self-evident that the game would not be the success story it needed to be.

However, had they not worked on the game for so long, they wouldn't have built and launched Slack. Inside the game company, the team was using IRC for communication. Gradually they started to build additional interfaces and functionalities for IRC. This was the foundation on top of which Slack was built. If Henderson and his team would have moved on after the first two years, Slack wouldn't exist. At that point, all they had was IRC.

In the startup scene, the common advice is to know when to pivot, or quit and move on. Henderson and his team didn't know when to pivot nor did they know when to quit. Their product kept failing until it was eventually shut down. But because they were too scared or foolish to pull the plug on their game, they now have a company with a valuation of US$7 billion.

I don't really know what to make of this story. Except that your human experience in this world will continue to be ruled by randomness and luck. You will continue to miss-out because you do the smart thing and succeed because you do the wrong thing.

Build trust

This brings me to my last takeaway from Slush. If you have no idea what to do with your team or your product, then how about just focusing on building trust?

Brian Halligan (CEO of HubSpot) talked about how customers' trust in sales and marketing is at an all time low. This is of course a symptom of a larger erosion of trust in our society. We don't trust our politicians or media. Something that is even more tragic is that more and more people struggle to trust science and medicine–two major cornerstones of human advancement.

But let's bring this idea to a more ordinary, everyday level. Halligan's talk got me thinking about how often do I feel deceived or let down.

I don't mean this as any kind of criticism towards the organizers of Slush (because y'all put a lot of effort and hard work into the event), or towards marketing and promotion in general, but one major issue with many of the Slush talks is that the amount of self-promotion is sometimes a little too much. The talks have catchy headlines and they start out strong but after five minutes in, you sometimes realize that the presenter has moved away from the actual topic and is now going through the different features of their software product. This happened to me a couple of times. And I have to say that it didn't feel nice. I felt betrayed.

Think about your life and those moments, big or small, when you felt that your trust was broken. Maybe you bought something of poor quality, read an article with a clickbait title, got blown off by a new acquaintance. It probably didn't feel nice. It probably sucked.

Now think about how much joy it brings to your life when someone respects your trust. Your customers, your audience, your friends and family are all craving for trust. You can become a more meaningful part in their life by just being more trustworthy. For example, try to be more consistent instead of bending over backwards.

Final notes

Last week I wrote about my Slush preparations. Even though the event is now over, you might find the post useful for your next big conference. Here is a link to the post.

Big thanks to everyone organizing the conference, all the speakers and all the people who I got to meet during the two days!

Surviving conferences

Dec 2, 2018

This week I'm going to attend Slush, a two-day startup and tech event of over 20,000 visitors. This is my plan for making the most out of the event.

Last time I visited Slush was four years ago. It was a great experience. I had fun, I met new people, and I picked up bunch of stuff from the talks. However, there were also moments when the dark event space filled with colored lights and lasers, noise, and the overwhelming amount of people was a little too much.

It's also not just the space that makes me anxious. I'm hoping to meet people and make connections. The introvert in me is not happy about this objective. As is the case with all networking, he is worried that the mingling is going to be unpleasant and futile.

To deal with these real challenges, I present my four-step plan for Slush (or any other big conference):

1. Make a schedule

I have scouted the talks I want to see and marked them in my daily agenda. I know that I can't fully avoid the disorientation that comes with large event spaces, but I can make a plan for where I want to be and what time. I can try my best to avoid decision making during the event days.

If you can limit the amount of decisions you make in a day, you can try to reduce decision fatigue. A reduction in decision fatigue is an increase in overall energy levels.

2. Take breaks to recharge

What do you do when you are feeling exhausted? You rest. You take a break to regain your strength.

I don't have to be talking to people and listening to talks the whole time. Most importantly, I also don't have to be in the event space for the full 8 hours. It's possible for me to have my breaks outside of the conference. I can hit the pause button for all the action.

There's a library within a walking distance from Slush. It's the perfect resting place. I can recharge myself by reading or just gathering myself in peace and quiet.

3. Prepare questions

This step is about networking. It's about preparing myself for starting conversations and keeping them up.

The key to great conversations is to showcase your interest to other people. If you want to be interesting, you first have to become interested.

So how do you generate that interest? You ask questions that aren't leading or that have no ulterior motives. You ask questions that are about getting to know the other person in a real way.

If you meet a startup founder or a person starting out with their project, ask them how they got in to the space. Ask non-founders if there is something interesting going on at their workplace. You can go even more generic: ask people what's going on in their lives or how their weeks started off.

4. Define goals

Define what a good conference experience looks like. How many talks do you want to see or how many people do you want to connect with?

My goal is to have three enjoyable discussions with different people and listen to two truly interesting talks each day. That is what success looks like to me. I don't want to leave the conference thinking if I should have pushed harder to get more out. I want there to be a point where I can be satisfied with my efforts to network and pick out good talks.

Final notes

If you also struggle with networking and conferences, I hope this plan can help you. And I hope to see you at Slush!

Organizations Are Not Teams

Nov 25, 2018

I currently work in a software agency of less than 20 people. Before that I worked in a company of over 4 000 people.

Moving from a massive organization to a tight-knit group of techies I assumed that the way I would interact with other people in my workplace would change dramatically. In my previous company, it was impossible to get to know everyone in our business unit. I would end up building rapport mostly with my team members.

When starting in my current company, I thought that I would create equally meaningful relationships with each one of my co-workers almost effortlessly. I considered the whole company to be my team.

Here's the problem: 20 people is small for an organization but large for a team.

Let's start with the issue of coordinating collective work. If you want to connect two people with lines of communication, one line is enough. If it's three people, you need three lines. Double that to six people and you need 15 lines. While your team size might grow linearly, your lines of communication won't.

The next issue is motivational loss. In 1913, French agricultural engineer Maximilien Ringelmann found that the more people you have pulling a rope in a tug of war, the less effort each individual will put in. When our team sizes increase we start to contribute less and less.

Lastly, there is the issue of relational loss studied by author and Ph.D. Jennifer Mueller. When we work in large teams we perceive a lack of connection to other people. Because of this, we feel that there is less support and help available for us. This leads to stress and low performance.

None of this means that I don't have a strong, meaningful connection to my company. Or that I don't care about my co-workers. It just means that I expect different things from different people. The support and trust I receive from my core team is different from the support and trust I receive from my workplace.

The feelings you have towards your current workplace might have a lot more to do with your current team composition than the actual organization itself.

Productive Conflict Is a Journey Not a War

Nov 18, 2018

Conflict at your workplace is unavoidable. It will happen. People will disagree: Everyone won’t see eye to eye on a budget estimate. There will be a product feature that divides opinions. The coffee brand served at your office will not be everyone’s favorite.

Conflict is not a negative thing or a thing to be afraid of. First of all, it’s bound to happen. Second, it can move your organization forward. Conflict forces us to listen, open our eyes to new ideas, and vocalize real problems.

But our way of dealing with conflict can be good or bad–productive or unproductive. And none of us are perfect. While we can be skillful with some areas of conflict and communication, we will fall short with others.

There are also ways of communicating that come more naturally for us. This is stuff that's part of our personality. Or stuff that we carry with us from our childhood homes, personal relationships, and cultural contexts.

Conflict avoidant vs. conflict seeking

To simplify things, your default way of dealing with conflict can be considered as conflict avoidant or conflict seeking. Instinctively, you either hide from conflict or you seek it out. Neither is better than the other but in the extreme, they are both unhealthy.

I have heard these two types of conflict styles compared to battle tactics: you either build a bunker and hide from the enemy or you jump into a tank and charge the enemy position.

The problem with these kind of tactics is that you are preparing for a war where there are winners and losers. You are not preparing for a journey where everyone will better off in the end.

By default, I personally seek out conflict. When a conflict suddenly emerges I usually charge towards it rather than run away from it. This means that from my side, poor conflict resolution is often caused by over-aggressive communication. I push too hard instead of calming down and really listening what the other person has to say.

Being present in conflict

Even though you might be aware of what’s your conflict style, you won’t automatically learn how to avoid unproductive communication. This is because with conflict comes feelings and emotional responses. Feelings make it harder for us to control ourselves. We get an urge to either shut down or attack.

Instead of denying your feelings, you should acknowledge their existence. After that, try to dig a little deeper and articulate your feelings for yourself. Try your best to be honest. Do you have a need to be right or a need to be seen by the other party? Are you afraid that the other party doesn’t care about the issue as much as you do?

If you know your default conflict style and you are able to identify your feelings, perhaps it will be easier for you to prepare yourself for situations where conflict might arise.

This is a hack from author and business thinker Nilofer Merchant that I want to give a try. It’s taken from Merchant’s article about the importance of listening when creating change. It's a practice you can do when preparing for meetings, workshops or any other events:

Find an index card or sheet of paper (a paper napkin will also do). On one side, write key ideas that could be useful for you to share. […] On the other side, brainstorm questions you want to ask and things you hope to learn.

This practice forces you to make a physical act to acknowledge that it’s at least as equally important for you to listen than it is to talk.

It’s not important if you don’t get to ask the questions as they are written down. What’s more important is that you have primed yourself for curiosity and listening. You have primed yourself for a journey, not for a war.


Are you conflict avoidant or conflict seeking? What can you do to become better at conflict resolution?

Next page