How I started documenting at a new company

I once got a job at a company that was acquiring a massive piece of intellectual property from another and it was my task to build a team to maintain and transition the knowledge as well as running assets (servers, databases, etc). The company that hired me had no relevant the documentation and the IP we were buying came with very little and all potentially obsolete. Everything was a matter of asking random people one after the other piecing together the puzzle until the answer was built. Oh… and I had 6 months to get it done.

The process of starting to write documentation was very daunting, so I created a new type of document that I named “Exploration”. An exploration is frozen in time and describes something that happened, was found, discovered, figured out, etc. For example an exploration might say: “My boss asked me to add an account, I didn’t know we had accounts. I asked Johnny and he said Sally used to do it but she left. I asked my boss who replaced Sally and I was told to talk to Sam. Sam told me how he adds accounts, the steps are 1, 2, 3, 4. He doesn’t know what step 3 does but he knows that if you don’t do it, the account doesn’t work.”

An exploration is frozen in time and describes something that happened, was found, discovered, figured out, etc.

I bet I’m not the first one to come up with this concept, but I haven’t seen it anywhere. Have you?

The goal of the explorations is to quickly form a written corpus of documentation about “How do we do things here?”. This allows you to depend less on people, which is very useful during transitions or turbulent periods where people might leave.

One of the key aspects of explorations is that they are narrative, informal, and not necessarily high quality. It’s hard to write the manual so people don’t do it. Specially if it’s a big manual of which nothing is written. The exploration is a brain dump.

Explorations should be stored in a centralized documentation system that’s easily searchable. My preference is Confluence (maybe using the blogging feature), the cool kids are using Notion these days. Stay away from Google Docs, because it promotes private copies and there’s no way of having a single tree or directory of documentation. Being able to easily search all explorations is very important and they should be searchable with the rest of the documentation.

Explorations sometimes evolve into proper documentation, procedures that are maintained and live. When that happens, I often have a See Also section in the document that points to the explorations that influenced it and at the top of the explorations I add links to the document. It’s important to note that explorations are tier 2 documentation and it’s important that everybody knows it so that they are not taken as truth when read and are written liberally.

The frequency at which explorations are created changes depending on what’s going on at the company, but generally people should be writing them any time they faced something puzzling. The way I do it is very simple: I constantly debrief with my team about what they did and after they told me the story of what happened, what they did, the workarounds and we have a good laugh, I almost always say: “Please, write an exploration about it”. It takes some effort to get started, but I think often people realize not having to remember things and just making brain dumps has a lot of value. Eventually they would just write explorations without me asking.

Don’t expect explorations to have an immediate effect. It takes time to build a corpus of data that is worth searching for answers. It might take you a year to get there.

A manager should multiply, not add

If you are managing a team of people that are transporting rocks from A to B and you spend one hour picking ups rock from A and dropping them on B, you added one hour of work. If you spend that one hour procuring wheeled carts so that people don’t have to carry rocks on their backs, you increased their performance by 25% (and happiness). One task makes you an adder, one makes you a multiplier.

And this is very semantically correct. If your team has 0 people, increasing 25% of 0 is still 0. Your effort was wasted.

If you are a multiplier, the more people you manage, the more impact you have. That’s why often the compensation of a person at the top of a huge organization is so big (not to say that current CEO compensation is correct, that’s another story).

I find this is a good heuristic to know if I’m working on the right thing as a manager. Am I adding or am I multiplying? Sometimes I have to add, but if all I do is add, am I a manager?

The output of a manager is the output of the organizational units under his or her supervision or influence.

Andy Grove, High Output Management

Something to keep in mind is that multiplying is hard. Well, it’s hard to find the opportunities when you can multiply. You need to sit down, look at the team carrying the stones, think about a better way, go find some carts, get a quote, evaluate it, run an experiment, see the increase in performance, discover not everyone knows what to do with it, write the manual and the training program, stop everyone from carrying stones (temporarily dropping productivity) so they can learn to use the wheeled carts.

If as a manager you are so busy with interruption work that constantly lands on your lap, busy doing adding work, you will not have the time and mental space to think and find opportunities to multiply. This is why I don’t like the always-busy CEO or always-busy manager. When do they do their thinking?

If you want to learn more about this I highly recommend Andy Grove’s High Output Management.

Standups should be asynchronous

Quick definition:

A standup is a type of meeting commonly done in software development teams and now expanding to other knowledge working teams. During the standup meeting you say what you’ve done, what you are planning to do, and whether you need help or are blocked. Normally they happen daily and they are called standups because traditionally were supposed to stand up in front of your desk and just share with everyone else. The idea is that by standing up, people would be brief… that is often not the case (I worked at a place where standups would take between 20 to 60 minutes for about 6 people).

The idea of the standup is that the whole team is on the same page, but in my opinion, most developers zone out until it’s their turn, they say their bit, and then they zone out again. The only person paying attention to everyone is the manager. And generally there’s nothing bad with that except that we are wasting people’s times.

There’s a problem with the standup though, which is, at what time is it supposed to happen?

  • 9? too early for most developers
  • 10? ok for most, but those that show up at 9 will do nothing until the standup, because why bother getting in the zone if you are getting to get pushed out of it.
  • 11? now almost everybody spends most of the morning doing nothing because of the upcoming interruption
  • 12? just before lunch? maybe… at least people will keep it brief! But those that eat later will get annoyed by the interruption.
  • Any time in the afternoon? are we talking about today/tomorrow instead of yesterday/today? most people don’t plan tomorrow’s work and thus the what-will-you-do? part will be of low quality. Oh… and those that are not morning people will get their most productive time interrupted.

The solution is very straightforward: asynchronous standup. People just give a brief report to the manager, but in a public space, about their plan for the day and what happened yesterday. I guess you could do it face to face, but that’s awkward. Text asynchronous standup are much better and they are friendly towards distributed work. They have a second advantage: track record.

The standup is one of my most useful tools for management. I don’t expect members of the team to read each others report, but they are all public. If I notice a conflict or a potential synergy, I may ask someone to look at someone else’s report.

If I don’t understand something, I drop a question. If someone has been working on the same thing every day for too long, specially if they mentioned they were close to finish, I have a chat with them (could be a task is problematic, blocked, a drop in performance, etc). If someone is planning on doing something that shouldn’t happen, I jump immediately.

As a manager, it’s yet another opportunity for me to give encouragement to individual members of my team about their work, to thank them for doing the crappy tasks that nobody likes, etc. I sometimes push myself to do that, because otherwise the standup could start feeling like a useless bureaucracy, writing something that nobody ever reads, a thankless task. I want my team to know I’m reading it, paying attention, finding places to help, etc.

I generally use Slack for text communication for my teams and my favorite app for asynchronous standups in Geekbot. It’s good if you are together, essential if you are distributed.