Documentation for Data Systems

How do I as a data professional communicate with my colleagues, my peers, myself in six months, and with the person we are going to hire next year?

How do I leave something behind for my colleagues to learn and access the thoughts that I had when I built something investigated something learned something or understood something?

I write this from the perspective of a data professional, but I really think this is pretty broadly applicable to most companies where people have to ask other people questions to learn information to get their job done. So really a lot of companies probably 🤪

Basically I think this boils down to 4 super related things that are needed to write and contribute documentation to your company and your colleagues.

1. Accessible & Findable - Make sure it's open to the team that needs it, and that they can find it
   
2. Incomplete & Living - Make sure you spent the appropriate amount of time and not a second more, but also that others' can extend and pick up where you left off

Accessible & Findable

Make sure it's open to the team that needs it, and that they can find it

In order for documentation to be used, it has to be open and findable to the team needing it.

This may seem simple but many a time I have tried to open a document and found the permissions locked. Or looked for a document I knew existed, but been unable to find it and had to ask around.

The companies and teams that move the fastest have open access to the data and information they need to accomplish their mission.

Incomplete & Living

• Don't write everything
• Don't try to capture everything
• Don't try to solve every problem
• Don't try to store every detail
• Don't try to tell everybody everything
• But also
• Don't think that communicating status and state is not your problem
  

Do write what you know right now, and/or is at your fingertips, and also be done and leave TODOs and open questions.

A company, a project is like a quantum state. You can't actually know what's happening at any given point in time even if you had all the information. And having all the information would alter the system to an unknowable state.

Just aim for 20 minutes, leave open questions, and make sure the doc is accessible and open for updates and permissions, and come back! next week! next year! tinker, and a line here and there and see where it grows to 🌱

Wrap it up

todo there is more to say on wrapping together Accessible, Findable, Incomplete and Living.

Conclusion

Spending 20 minutes writing a piece of documentation is usually going to be a waste of time 😧

but

when you hit you hit big. Write 10 docs that take you 3 hours, and one of those will save someone between a day and a week of time.

In conclusion ⤵️