The Clearly Podcast

Documentation

Summary

Documentation is often neglected in many IT projects.  This week, we talk about why it is so important, and the risks involved if you don't do it.

Some of the most fundamental things you need to document are:

  • Passwords - and do it securely in a password vault

  • Data dictionary so everyone knows how measures and KPIs are defined

  • Configuration - so there is a clear understanding of where everything lives

  • Reasons behind decisions - because there might be a good reason for not doing something in the obvious way

How you do it is up to you and your use case - it's important that it shouldn't become too onerous, and Agile is no excuse for not doing it - if all your developers leave with all your service account passwords in their heads, you're sunk.

And documentation can be as simple as a OneNote notebook and comments in code, or something more complex such as a set of Confluence pages.

But however you do it, make sure you ACTUALLY DO IT!!

You can download Power BI Desktop from here.

If you already use Power BI, or are considering it, we strongly recommend you join your local Power BI user group here.

Transcript

Andy

  • Bonjour Masami.

Shailan

  • No, hello.

Andy

  • We've got a listener in France, so I thought I'd start in French. Today, we're talking about documentation. It's not the most exciting topic, but it's essential. The main point is: just do it.

Tom

  • Yeah, that's basically it.

Andy

  • So, let's discuss why documentation is important, how to do it, and tips for maintaining it. Tom, why is documentation crucial?

Tom

  • It's important because you can't rely on individuals to remember everything. If someone leaves or gets sick, undocumented information goes with them. Documentation ensures continuity and saves time when someone new steps in.

Andy

  • Exactly. We've all faced projects with no documentation, struggling to figure out setups and configurations. Shailan, can you share some experiences?

Shailan

  • Sure. For example, in Power BI projects, we've had cases where the data sources, refresh schedules, and security settings weren't documented. This leads to delays as we reverse-engineer everything. Even simple documentation like data source locations and refresh frequencies can save a lot of time.

Andy

  • Yes, it's often not just about the "how" but also the "why." Understanding the rationale behind certain setups is crucial. Tom, you mentioned issues with metric definitions and password management due to lack of documentation.

Tom

  • Absolutely. I've seen projects where the same metric had different definitions because there was no agreed documentation. And once, I nearly got a call from a former employer because they couldn't decrypt a database backup. Luckily, they found the documentation I left behind.

Andy

  • How many times have we had to reinstall Power BI gateways because the password was missing?

Tom

  • Too many times. It's a huge time-waster.

Andy

  • Let's talk about practical ways to document. It doesn't have to be a big Word document. It can be a collection of artefacts like wiki pages, OneNote notebooks, or even comments in your code. The key is to document as you go.

Shailan

  • Agreed. Documentation should be part of the process, not an afterthought. An architectural diagram can also help by showing the overall process and data flow.

Andy

  • Great point. Make your documentation searchable and easily accessible. Tools like SharePoint, OneNote, and password managers can help organize and retrieve information quickly.

Tom

  • Documentation should not be a big burden. It should be a natural part of your workflow. And don't hide behind agile principles to avoid it. Agile doesn't mean no documentation; it means effective documentation.

Andy

  • Absolutely. Documenting as you go helps you remember the reasons behind decisions and keeps everyone on the same page.

Shailan

  • If a client says they don't need documentation, they're usually trying to save on resources. But it's crucial to argue for its importance because it doesn't have to be costly or time-consuming.

Andy

  • Exactly. Good documentation habits can save time and prevent issues down the line. Any final tips, Tom?

Tom

  • Treat documentation as a process, not an event. Make it a natural part of your workflow, and use whatever format works best for you and your team.

Andy

  • Shailan?

Shailan

  • Document as you go, use various artefacts, and have an architectural overview. These practices ensure clarity and continuity.

Andy

  • My tips: think about all the different things you need to document, make it searchable, and use a centralized place like SharePoint. Just make it a habit. That's it for today. Remember, documentation is vital, so just do it.

Tom

  • Cheers, everyone.

Shailan

  • Thanks, all.