September 29, 2019

How and why I document processes

Olga Shavrina
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 an 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 nuances. Later I found out there were lots of nuances 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 a documentation up to date".
What I found out
Pretty soon it became clear that everything is more complicated than it seems - conditions and "IFs" were on 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 pat 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 quite a 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 to my head and soo 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. The half of questions was about automatic emails – what we send, when and to whom.
The first scheme
At some point I just sat down and made a scheme describing the first step of the funnel – what's going on from the moment a client makes a request to the moment they get an offer.
Diagram: from request to 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 details.
Tiny email screen is hidden on the scheme, but you can zoom in and see it in details
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 the place – everything becomes clear in seconds. It's a success, I think :)
After that I was unstoppable...
I loved the effect it made! Also, I enjoyed the process of cleaning around 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. Not it looks like this:
Schemes of all main processes in Nautal by the moment I wrote this post
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 process related 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 e store all documentation. When a process change – I add a new scheme with an update date and store the previous one for the history in order to be able to answer question like "When have we changed this thingy?". Developers and managers have an 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 rules 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 relates to. Sometimes I use red comments if it's necessary to highlight a problem or an important fact.
Notation – events, emails, conditions, "Swim Lanes" to specify roles
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.
One big scheme or several smaller ones?
I found it useful to make separate schemes for the logically completes 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, it 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 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:
The process from request to offer from the automatisation point of view
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 makes much sense in a startup, but a clear diagram that can be easily updated – does help a lot:
Less questions to you personally – people can find answers themselves.
Less errors – in managers' work, in developers' work and in your work.
Faster and more reliable way to find answers when they arise.
Huge respect from all the team – people see that you invested your time in order to make their life easier.
Plus, a free bonus – you can enjoy the process, because isn't it wonderful to do something beautiful, elegant and useful? :)
Olga Shavrina
Product manager
Made on