How and why I document processes

When I came to Nautal, everything seemed pretty simple. Airbnb-type marketplace but for boats. What can be complicated? During the onboarding process, my manager explained the overall process – a client makes a request, boat owner sends an offer, client pays, boat owner confirms the payment.

He mentioned though that in some cases there can be variations. Later I found out there were lots of variations and almost no documentation. We are a startup – what documentation you are talking about, cmon? An official version was "everything changes so fast, that it's impossible to keep any documentation up to date".

Pretty soon it became clear that everything is more complicated than it seems - conditions and "IFs" were in every step of a boat booking process. A client can order a boat with or without a skipper (captain), can pay online or via bank transfer, in one sum or split a payment, can pay part of the payment in cash at check-in. A boat owner can send several different offers for one request, also an offer can be sent automatically by the system or manually by the manager. A confirmed booking can be changed – you can add extra options which could be paid also in different ways.

In the beginning, in order to design a new feature or an improvement, I had to invest a lot of time to find out how it works now. And pretty often I found out that nobody actually knew it. So I had to go to developers and ask them to look into the code.

The information was sticking in my head and soon I found myself being a source of knowledge – people started to come to me and ask questions. Pretty often I saw the same people who forgot a given answer or just couldn't apply the logic to a slightly different case. Half of the questions were about automatic emails – what we send, when and to whom.

At some point I just sat down and made a scheme describing the first step of the funnel – what goes on from the moment a client makes a request to the moment they get an offer.

I use a Miro tool (it was called "Realtimeboard" before). Super useful – everything is on the same unlimited board, you can drag and zoom as you want. Zoom appeared to be extremely helpful – I add small screens of emails directly to the scheme, so they don't clutter the scheme up, but you can zoom in when you need it and see an email in detail.

I printed the scheme, gave it to managers and explained how it works. Finally, I saw the understanding in their eyes and sincere childish joy. The number of questions decreased significantly, when they pop up, I take out the scheme, point to the place and everything becomes clear in seconds. It's a success, I think :)

I loved the effect it made! Also, I enjoyed the process of cleaning up and making sense out of the chaos (it's my superpower :)) so I dived into the main flows and made schemes on each of them. Now it looks like this:

And that's only the main process without details.

Developers also appreciated my initiative. When I formulate the task in Jira I attach the scheme of a related process and explain what should be changed and how. Considering that we speak Spanglish that is not native to anyone in the team, images help communication a lot.

I publish schemes to Confluence where we store all documentation. When a process changes – I add a new scheme with an updated date and store the previous one for the history in order to be able to answer questions like "When did we change this thingy?". Developers and managers have access to Confluence so they can check it any time they have questions.

I found out an interesting side effect – other guys from the company started to use the same approach for their processes. Sometimes I see finance or sales guys drawing schemes in Miro.

There's no strict rule in drawing processes. Yes, you can use UML if it works for you. I use a bit different and free notation – my emails are yellow rectangles, events – green or red rounded rectangles, conditions – diamonds, actions – texts, notes – grey italic text with a dotted line that shows what notes relate to. Sometimes I use red comments if it's necessary to highlight a problem or an important fact.

If a scheme describes a process for different roles – clients, boat owners, managers – at the same time, I use "Swim Lanes" to make clear which part of the scheme corresponds to which role.

I found it useful to make separate schemes for the logically completed steps of the process. More or less I try to use 10-20 blocks on one scheme. If there are more – it's hard to comprehend, if less – not informative. Plus I try to make the scheme readable on the A4 paper size.

I place the schemes on the board in a logical order. E.g. from left to right:
1. The process from request to offer,
2. Payment,
3. Confirmation,
4. Second payment etc.

Sometimes I draw the same process from two different points of view. For example, one big complicated scheme with all branches and two simple schemes for two extreme cases. Say, if a part of the system is automatised it is helpful to see auto and manual scenarios separately in order to understand the difference.

The example below – is the same process that is on the scheme at the beginning of the post about the process from request to offer, but here it shows two different cases – when we do and don't send auto offers:

Don't stop yourself when you want to clarify and document your processes. Everybody wins from this initiative. Well, long and hairy documentation maybe doesn't make much sense in a startup, but a clear diagram that can be easily updated – does help a lot:

Plus, a free bonus – you can enjoy the process, because isn't it wonderful to do something beautiful, elegant and useful? :)