Logbook, a great practice for distributed teams, long term projects and products.

Logbook, diary, journal, bitacora… there many names for the same practice: write down what you do. This practice has been used among sailors and scientists for centuries, for good reasons. Nowadays there are plenty of tools to keep track of what you do but I haven’t seen anything as powerful as a team, a project or a product logbook.

Five years ago I wrote an article about my first interactions with this practice, back in the beginnings of my professional life, in the Canary Islands, Spain. The article describes the basics of any team or project logbook. You would benefit from reading it before you keep reading this article.

I would like to provide some additional insides about the diary, together a few tips and practices I have used throughout the years.

Why is the logbook useful

Keeping a logbook is useful for:

  • Engagement: you will know about what your colleagues are doing. They will know more and better about what you do. All in a contextualize manner.
  • Alignment: the logbook will reduce the need of coordination and providing status to your colleagues. It will also help in advancing divergences among team or project members. Managing dependencies better is another outcome.
  • Reporting: the logbook allow to turn the reporting activity into a pull system. Instead of providing a report to your manager, for instance, she can pick up the relevant information from the logbook. A similar thing happens when you need to provide a status report to a customer or another team. A significant part of such reports should be already in the logbook or link to it.
  • Analysis / retrospective: quarterly or yearly reviews are simpler when a logbook exists. Postmortem analysis also becomes simpler.
  • On-boarding: when a new developer joins the team for instance, the diary helps a lot. The newcomer can learn a lot about the team activity, hot topics, who is who etc. by reading it as one of her initial activities.

Who is the logbook for

Everybody would benefit from contributing to a logbook but in some situation or environment, this practices provide significant benefits:

  • Remote teams, specially those distributed across different time zones. The fewer overlapping times, the more benefit you get from the diary. Engagement and alignment become key factors here.
  • Long term projects or products: the analysis / retrospective element makes the logbook a beneficial practice.
  • Teams working on more than one project (multitasking): teams that work in more than one project benefit a lot from having a log book per project and/or a team log book. In this case last case, you might want to consider a per project tag. Reporting is another obvious argument for using a logbook.
  • SWAT teams: engagement is the main factor here. Alignment is also an obvious factor, specially in management teams.
  • Large teams: the benefit here, beside those explained already, is the reduction of the need to provide status in the different team ceremonies, maximizing discussion, retrospective or brainstorming time, for instance. The status information is already recorded on the diary. Go and read instead of repeating already documented information.

Git based vs wiki

I always recommend to use a git-based tool for the logbook. It is not just that collaboration is easier, especially for developers, but also allows to integrate the habit of writing in their workflow easily. It will also be easier to structure and visualize the information through tags. Git is specially convenient for distributed teams too, which are the ones who benefit the most from this practice in terms of alignment.

Often the diary is used by people who does not know how to use git or is not part of their day to day workflow. I have had jobs in which I did not use git on regular basis. In such cases, a wiki can be the best option. Make sure you use a wiki with conflict resolution capabilities. Otherwise, the logbook will not scale. If you use a wiki that structure pages in editable sections, that might work too.

There are tools that combine the best of both worlds, like Gitlab, Github or zim-wiki. These are my favorites.

Structure and archive

I recommend to structure the logbook per day and per user. It doesn’t matter if we are talking about a product/project diary or a team one. Other options are possible but it is simpler to write down your entries one after the other one and use the tags to open the possibility to structure and visualize the information later on in different ways.

To use the logbook as reporting tool, at some point the write permissions should be removed. From that moment on, past entries should be amended in today’s section, not modified in the corresponding date.

When should the write permission be removed?

I suggest to do it weekly by default. I usually lock it down the following Monday at lunch time, providing the possibility to those who forgot to add their entries on the Friday before or were absent for whatever reason, to add their entries.

Project or product logbooks might use the sprint as the iteration, specially in cases where those sprints are two weeks long. But in general, if you have a good number of people writing in the logbook, I prefer a week long iteration.

To archive the diary, I usually move it away from the current one. I personally prefer to avoid scrolling or information from many days where I write. So I use a different file for past entries and current ones (that week). If you are using a wiki, move the content to a different page in read-only mode.

When and what to write?

As mentioned in the original article, you should include in the logbook what is…

  • Relevant to you.
  • Relevant to your peers.
  • Relevant to those you interact with like, managers, other teams, customers, etc.

Write down all the relevant events or any relevant information as soon as you have it. Write down what has been completed, solved, blocked… State facts and ask questions instead of writing opinions. Leave the judgement for the later analysis of the logbook. Keep them out of the logbook entries unless you create a specific tag for it (#self-note could be an example).

I add an entry at least every couple hours, before taking a break, except when I invest a longer period of time in an intensive task. So I usually have four entries or more daily in my logbook. I tend to write a lot more though. Other people write less than I do and that is OK as long as each one of us write down the relevant information for ourselves first, for our colleagues and finally to others.

Include decisions and agreements, conclusions, achievements, pitfalls, mistakes, external events that have influenced your work, external references and data sources that were relevant, etc. But remember, the journal is about what you did, not about what you need or should do, what is coming or what you think. Later on, with practice, you can expand the nature of the content. Make sure you agree worth other writers on this topic. It helps to keep the logbook clean.

One special type of entry is a comment on somebody else’s entry. I recommend to use it at the beginning only to add information or additional context to somebody else’s statement, not to provide any opinion or question. This is a journal, not a forum.

Ask yourself this question, what would I like to read about what any of my colleagues or myself are doing in 3 weeks or 3 months time?

How should I write?

Be concise. One or two lines maximum per entry is the best approach. Add links to the information sources, to the tickets, messages, bug reports, patches, logs, web pages… where the information is really generated and stored. Provide context to those.

Use ways to shorten the links to those common tools you use at work on daily basis. Add tags like dates, names and any other metadata that can help to contextualize and structure the information later on.

Remember, whatever you do, make it simple so adding information to the logbook is easy and fast.

Tags

One of the key elements of the journal is the capacity to structure and visualize later on the information through tags. As mentioned, the logbook is structured by date and user (two tags), but there are others you can and should use. The more experienced the team or project is with the logbook, the more tags can be used.

Warning: agree on the tags with your colleagues up front, otherwise you loose part of the filtering and visualizing of the information capabilities later on. If there is more than one logbook at your organization, agree on the tags with the other teams and projects. Define common tags.

I recommend to start with very few tags and increment their number over time. The tags to start with might depend a little on the environment, the type of team or project. These are the ones I commonly start with:

  • date and user
  • Mood: 😀 , 🙂 and 😦 Use these tags in entries but specially by the user tag, to let others know how you feel and to be able to evaluate later on your mood in different time windows.
  • Escalation: #red #amber #green Agree with your team and/or manager the meaning and reaction to each one of these tags.
  • Absence: #sick and #vacation Use them by the user tag to tell others that you or your colleague are absent.
  • Others: #decision, #agreed and #self-note

The tags are usually located at the end of the entry. There is one exception. When you are commenting on somebody else’s entry, start with the user tag and some indent. Check the example below for this case.

Different tools might have different restriction about how to define a tag. Some have restricted keywords. I added the symbol “#” because it is a common one. For users, many tools use the “@” symbol, for instance.

Use standard emojis instead of tool specific ones. Again, make it simple. Consider emojis a tag.

Example

This is a simple example of how the journal would look like:

May

02/05/2020

@toscalix 🙂

  • Blog post finished. Referenced previous entries.
  • Could go out to do exercise for the first time in over 50 days of confinement. I will go back out again tomorrow. #decision
  • A new tag #off-topic has been created #agreed

@peter 😦

  • Blog post reviewed. Ready to publish #decision
  • Network issues again. Third time in two days #amber
  • Send any policy to @toscalix before approval for review #self-note

Conclusion

Keeping team, project or product logbooks is a very useful practice. In the short term increases engagement and alignment, in the mid terms reduces the effort in reporting. In the long terms keeping a journal improves analysis and retrospectives. on-boarding is another topic that heavily benefits from the existence of a diary.

I would like to know about your prior experience with logbooks or similar practices. If you want to try it out, feel free to contact me for questions or advice.

Working in distributed / remote environments 1: daily short meetings.

Agile establishes conversations as one key principle. The set up in those companies that follow agile methodologies are designed to maximise the interaction among developers and other people involved in product or service development. When working in distributed environments, the need to have those conversations does not change, but since the environment is significantly different, the required set up must adapt which affects to processes and practices. An immediate question comes to mind…

Should we do stand-ups?

My recommendation is to not have stand-ups. Instead, substitute them for a different type of meeting, with a slightly different goal.

The new meeting

The name

Let me start by the name. I like to avoid calling these meetings stand-ups to minimise the association with what most agile methodologies propose. Different goals, different set up, different dynamics… different name.

These new meetings I have run in the past, have been heavily determined by the availability of the participants (time zones, productivity peaks of each participant, breakfast habits depending on participants culture, etc), the set up (partial or fully remote, for instance), the company culture, the nature of the team (with fixed or variable/flexible composition, with the participation or not of stakeholders, etc), the room I have as manager to propose these kind of actions, etc. I have used several different names like sync-up, fast-track… meeting.

I really do not care about how to call it as long as we do not use the word “stand-up” to avoid a direct association to the agile ceremony.

Mandatory?

Nowadays it is common among distributed or remote teams that most developers agree on having short, daily meetings, but there used to be a time in which I faced strong opposition. Back then and today, I tend to avoid making them mandatory. I promote them by example instead. In my experience, this is one of those topics where peer pressure works better than top-down or a general policy approach, specially when senior developers, reluctant to participate, are involved.

The video chat tool

There used to be a time in which finding video chat solutions that worked on Linux was the main challenge, whici was the excuse to push back on these kind of meetings for many. Phones/Android has come to my rescue many times in the past. Hangouts were my preferred option for a long time. Although now there is a wide variety of options that works on Linux, in combination with the Google Calendar, Hangouts (now Meet) is still my favourite.

As manager, I have faced several obstacles with the video chat set up that I have had to overcome.

  • Technical limitations: I named the lack of solutions for Linux during a long time. Another challenges has their origin in the limitations employees face on the applications they can install on their machines. This is becoming less of a problem nowadays since more and more companies are understanding how important it is to provide at least one on-desk video chat solution. When working in environments where people from different organizations participate like consortiums, you end up with several video-chat solutions installed. Configure each one of them so they do not collide, which can become a challenge. Again, Android has come to my rescue a few times in such situations.
  • Legal considerations: legal restrictions have to be considered in every case. Using freemium services, for instance, or free accounts of commercial video conferencing service providers for internal topics is unacceptable in my opinion. Convenience has limitations. Having managed corporate teams that work in the open for some years now have made me familiar with this issue early-on. An “open by default” policy helps to overcome many of these challenges but any team needs a channel that meets corporate standards when discussing through video chat internal topics, no matter if you the team is working in an Open Source project, a standard company or a consortium.
  • Business considerations: GitHub has been recently bought by Microsoft. For those who compete against Microsoft in a specific market, or are providers of those companies who do, the purchase might bring challenges. The same concept applies to the use of video-chat tools. Google Hangout or Skype, for instance, might be great but not compatible with the activity your company develop for a variety of reasons. This factor needs to be considered when choosing a video-chat tool.
  • Religions: we all have prejudices/biases. Very frequently engineers install in their machines all kind of programs downloaded from a variety of sources to do their job, but they refuse to install a plug-in from a specific vendor to use a specific video conferencing option. Most sales people I have worked with are devoted members of the “Apple Religion“. Many designers are so used to paying for their tools that they become suspicious when an Open Source tool is offered to them with little or no cost at all. I am a Firefox user, I dislike solutions that requires a specific browser. As irrational that these and similar examples might sound when it comes to choosing a video chat tool, I tend to put effort in satisfying team members biases as long as no freemium services for company meetings are used and there is an available option for Linux users.

I am currently using the following tools on regular basis:

  • appear.in for BuildStream project (paid account).
  • Hangout/Meet since Codethink, the company I work with, uses some of the Google services.
  • Zoom for Linux Foundation stuff, since I represent Codethink in that consortium.
  • Skype for conference calls or regular phone calls.
  • Onconference for some meetings at Codethink.
    • People who work on the road, specially sales people, tend to prefer the phone over video. For these cases, where some people join through phone and some through video chat, there are solutions out there that work very well so you do not need to choose between one or the other way to connect. You have both.

The main goal is to have productive meetings where everybody joins because they feel that is important, without you as manager having to worry about legal issues. In general, I think that the tool should not get in your way as manager. Nowadays there are plenty of good enough options. Try several options before sticking with one and be ready to change it and have more than one.

Where?

One of the ideas I like about agile is the co-location concept when it comes to the office set up. The best way to translate some of the benefits that such agile practice offer into distributed and remote environments (DRE) is to join the meetings from your desk. It reduces the preparation time and the overhead associated to meeting rooms reservations.

Even if part of the team is at the same office, my recommendation is that everybody live the same experience during a meeting. Use your laptop or PC and get a headset. Mute yourself when you are not speaking, raise the gain of your mic so you can whisper and be perfectly heard, which helps to not disturb those colleagues around you, and enjoy the ride.

When working from home, I recommend to use headsets too, so people hear you with no echo, your dog does not become a participant, etc. I do not always follow this last advice because my current set up at home is a good one. I should anyway.

Meeting goals and dynamics

Duration, start and finish

Due to the nature of the channel used, short, daily meetings will need to be slightly more structured than stand-ups, which normally increases their duration. Try not to pass the 15 minutes mark including the “connection time”. It seems hard at the beginning but it is perfectly doable.

Due to the lack of face to face interactions on regular basis, short, daily meetings become essential for those working on DRE. While people connect, it is a good time to chitchat with your colleagues. Providing those initial 2-3 minutes before starting is frequently (not always) a good thing. Somebody got a haircut, the weather at somebody’s place is particularly sunny, a team member has a new banner at his office, it is Monday morning and one participant joins after her vacation… these are quality moments for any distributed/remote team. Honour them.

If the video-chat room closes when the chairman leaves, make sure the chairman keep it open a couple of minutes after the meeting is over. Again, chitchatting in this context is a good thing.

Stop reporting!

If you can only afford one takeaway from this post, take this one: in distributed and remote environments, meetings are not for reporting. Report offline, preferably in advance.

Meetings are expensive, hard to manage and exhausting. But in DRE, they are more expensive, significantly harder to manage and even more exhausting. I will talk about this more extensively in another post related with team meetings and 1:1 but, for now, I would like to say that because of these arguments, you should maximise the time for topics involving short discussions, brainstorming, dependencies discovery, opinions, etc.

So I recommend to remove the concept of “what I did yesterday and what I will do today”. Keep reports on the diary (I will talk about the diary in another post), promote a habit of reading the diary in advance and focus the meeting on topics leading to participation. And if you do not like the diary concept, use dashboard to visualise the WIP, described on tickets, make engineers report about their activity through mail on regular basis, etc. Whatever it fits your need except using meetings to report or communicate information that can be sent offline in advance.

Good practices

I like people to take these meetings seriously because they are really important in the long run. Sometimes I come across people that attend to these meetings while having a walk and smoking or they turn off the camera while doing something else. It is a consequence of the old school “conference phone call” culture.

I perfectly understand that attention does not necessarily depend on being in front of the computer and that a relaxed atmosphere is frequently a plus in some meetings, but I discourage these behaviours on this kind of meetings. I tend to be more flexible with “ad-hoc” 1:1 meetings.

No matter how informal these fast-track meetings are for you, think about those colleagues at the office who cannot do what you are doing, or the impact that generalising your practices might have on the team or the project.

In video chats, unlike f2f, somebody always need to be in control because you cannot afford having two people talking at the same time, due to technical limitations, for instance. Some formality is always required. Here are some tips to consider:

  • Create a routine that helps you to avoid moderation like:
    • Using a pre-determined sequence for providing turns. There are tools in which participants are ordered based on when they join, or their user ID, etc. Use those features in your benefit to reduce the need for moderation.
    • Favour those who join on time over those who arrive late somehow.
    • Make sure people join “on mute”.
  • Create key words for highlighting technical issues like somebody’s mic is not working or the connection “is choppy”.
  • Do not take notes by default but make sure people keep track of the action points or further conversations that needs to happen.
  • If something comes out of the meeting that requires in depth discussion, schedule a specific meeting. Make a note, say it out loud and move on. Keep “the flow”.
  • Make use of any possibility provided by the video chat tool to add labels or tags to your screen, like a state and emoji…everything that provides context or information about your state helps.
  • Provide the link to the video chat room in the calendar event.
  • Add 1 and 5 minutes notice notifications for these events. Those integrated with your desktop notification system are way more efficient than the mail ones for daily events.

Summary

I believe that remote teams benefit from having a short, daily meeting focused on participation over reporting, where there is some room for chitchatting, using a tool that everybody feel comfortable with, that also meets corporate policies and, when working in the open, Open Source community standards. The experience for every participant should be the same so I recommend having those meetings at your desk.

As soon as there is one distributed or remote person in the team, you are working on a remote environment. Adapt the short daily meetings to that reality.

Other articles of this series

  • 0. Introduction: introductory article where I explain the motivations to write this series of article and my goals.

The diary (aka bitácora): towards alignment in distributed environments

Introduction

There is a virtuous circle that many think is key for any organization to achieve success:

I want to focus on autonomy and its relation with alignment.

I do not know any single smart person that do not like autonomy. Definitely I want it and most of the managers and developers I have worked with too. There is no doubt that we achieve the best results for ourselves and the organization we are involved with with great doses of autonomy.

Autonomy though, as usual, requires high levels of coordination in order to be sustainable over time. It requires mechanisms of check and balance against a plan. Take a look at Scrum, for instance. It proposes to do checks and balances against the backlog every 2 to 6 weeks approx., at the beginning/end of every sprint And it forces also to establish a daily check and balance against the micro plan every day. That is a lot but it is the price to pay for getting autonomy.

And this is because the success of a group completely depends on the alignment of its members. Our tendency of “taking our own way” (entropy) is so high that organizations need people and many processes just to make sure everybody fight hard against it.

Definition and a little bit of history

I think it was 2004 when I started my relation with Fotón S.I. crew. Fotón is an open source company from Gran Canaria, founded in 1998, lead by Mike Vazquez and, back then, also by Gonzalo Aller.

Working with Fotón SI had a huge impact on the way I perceive management. It worked as a catalyst. I learned with them in a few months what takes ages for others.

Fotón was formed by a group of very talented and young hackers. The decision processes were very participant and transparent. Let me put you one single example: the basic accounting of the company was open to every employee, including salaries.

In their peak times they were around 20 people but it was strange to see more than 5/6 in the office. Most fotonians worked from home most of the time. They were based in Gran Canaria and my little company was in Tenerife. It was a distributed environment.

Going back to Foton, a key variable that balanced autonomy and alignment  in that distributed environment was THE DIARY, a simple concept but very effective. You can also call it journal.

Most people right now are probably thinking about that little notebook that needed a key to be opened where some boys or girls write their thoughts at early ages. Obviously that idea has little to do with what I am talking about. The term bitácora, a short way in Spanish to refer to the ship’s log, is closer to what I am talking about.

A bitácora is a log chronologically organized, written by the ship’s captain, kept in a wel define place where the most relevant events related with the ship, the crew and the journey where described. It had two main goals:

  • Analysis.
  • Report.

By writing on regular basis what happened in the ship, captains were creating a tool that allowed them to learn from past experiences. It was a very precious treasure, so precious that needed to be destroyed in case the ship got into the wrong hands. It was way more than the Black box of a plane. It captures the most important knowledge. If the captain got sick, for instance, or died in combat, his replacement used the bitácora to analyses the past history. Many of you are familiar with this concept since it is popular among scientists, archaeologists, etc.

The bitácora worked also as a reporting tool. After a few months sailing, it was impossible for any captain or officer to remember details about the trip if they were not written in real time. Providing a report about the trip was impossible without the bitácora. One interesting point was that, once written, no entry could be modified. If the captain made a mistake, he needed to create a new entry correcting the mistake, like in a check-book.

Fotón was a pret-a-porter development company organized per project. Each project had its own diary/bitácora. Following its culture, everybody had +xrw permissions in every bitácora. Agreed labels were used for different purposes: identify each user, assign relevance a specific entry through colours, etc. This idea was implemented in a hacked Twiki, integrated with Request Tracker and a mail service for notifications. A very smart, geeky, simple and efficient implementation for the time. Like all the wikies back then, UX was not the main feature but for console lovers…..that was no issue.

So Fotón extended the concept of the bitácora to a new level, going from an individual oriented tool to a group one, that is, they took a collaborative approach with a great result.

I still remember the day they explained and showed it to me. I was amazed, excited and cautious about its scalability. I was already used to write regularly what I was doing so the main hurdle did not applied to me: I had the habit. The collaborative approach was new to me though, together with the implementation.

How come something so simple has such a high impact? What makes reading what others do, think or feel so valuable? What is the relation of writing what you do and being efficient as a team? What a diary has to do with alignment? And here is the question that most people that face this tool/process for the first time ask: isn’t it the diary a tool to control me?

Let me start with the last one. The bitácora is a tool to control yourself. If you think you do not need to regularly check and balance your actions against your plans, your colleagues expectations and your company goals is simply because you are not senior enough, period. The diary is just a way to achieve that, like the stand up meetings or the burn down chart.

You decide what kind of information you should include in the bitácora. Here is the main rule. Knowing that is open to those you work with, add what you think is :

  • Relevant to you.
  • Relevant to your peers.
  • Relevant to those you interact with like, managers, other teams, customers, etc.

Do not add information that only one person should know about or that you would not say in a team meeting. Simply use your common sense. For instance, if I am frustrated about something…. I add it in the diary if I want to share it.

Fotón used to open the diary about a specific project to customers and third parties involved on it and it worked beautifully. Of course once in a while somebody wrote something inappropriate, but the benefits of these diaries were so high that assuming the damage was out of question. It became an outstanding engagement tool, as good as the best sprint planning meeting.

Very soon I experienced myself the benefits of getting the habit of writing regularly in those project diaries I was involved with, reading what others wrote and interacting with them through the diary. I got a sense of control of my day to day work and, even better, of what everybody else was doing. Control in a good way. Sync meetings were reduced, asking for weekly reports made no sense,… we were a more efficient, coordinated… better aligned organization, even in our distributed environment, despite working in several projects at the same time, with different customers, third party companies or different working schedule.

Conclusion

In many ways Fotón diaries laid upon two ideas that today are very popular: semantic and social (in a twitter way). I believe that the diary is a key complement to agile methodologies, specially in distributed environments.

In my next article I will describe in detail the concept and what the perfect implementation should look like, based on my experience since I have used it widely since then.

Series of articles

  1. The diary (aka bitácora): towards alignment in distributed environment.
  2. Bitacora: environment definition.
  3. Bitacora: personas
  4. Bitacora: Impact mapping

The following one will define the personas. This section will be updated with the coming articles.