Pablo Fernandez

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.”

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.