For four months during 2012 I was working on the GDS infrastructure team and one of the first tasks that Gareth suggested I do was update a diagram showing how all the different applications and databases worked together.
I thought this was quite a strange thing to ask the ‘new guy’ to do since I obviously knew nothing at all about how anything worked but he told me that was partly why he wanted me to do it.
I had to go through the puppet and application repositories to work out what monitoring we already had in place, which applications used MongoDB, which used MySQL, which called each other and so on.
If anything didn’t make sense I could go and ask someone in one of the application teams and then add my new understanding to the diagram.
As micro services driven architectures become more and more popular it strikes me that this probably wouldn’t be a bad starting point for anyone new to a system.
When you’re new you don’t yet have the familiarisation that makes things ‘obvious’ so you’re less likely to skip over things and more likely to be inquisitive about why things are the way they are.
As you come across things that don’t make sense others who have worked there for longer can play the role of the shaman who explains the history and context behind the decisions which have led to the current state.
Although diagrams can quickly go out of date I still think one of the whole landscape is useful as it gives everyone a common point of reference which can help reduce misunderstandings.
Pat Kua has a bunch of articles covering various different onboarding activities which are probably worth a read if this is your type of thing.