Help out your future self

I’ll be honest with you… I actually really enjoy building flat pack furniture. The step-by-step approach appeals to my way of working (I count out all the pieces before I start) and there’s a definite sense of achievement when you get the final product. However there is a situation where it’s less fun and becomes more stressful. This happens when there is ambiguity in the instructions - I’m sure you’ve been there. Exactly which screw is it? Which way up does this piece go? Have I missed a step??

There is a really clear link to how you think about the documentation of your model building process. Having a well written document of your steps will help you prove to regulators that you know what you're doing, make it easy to replicate the process if needed and answer all those quick questions that pop up over the lifetime of the model. Not only will your future team thank you for this, so will your future self!

So what makes good model documentation? Well firstly your documentation should not be Lord of the Rings. You should avoid telling the long twisty story of the last 6 months and instead focus on the key facts of the build: why you built the model, how you defined your data, how you built the model etc. Secondly I find it really useful to have a clearly agreed set of standards for where your code, data and charting can be found making it easy to manage and reference. Finally, where possible write your documentation in a way that makes your model easy to reproduce. If you do this you won’t spend the next 5 years wondering: where did I get that data from or how did I transform this feature? One big difference from the flat-pack instructions is that great model documentation also talks about the ‘why’ as well as the ‘what’. Make sure you not only explain the decisions but the rationale behind those decisions.

In summary, try to think about your documentation from the perspective of you in 5 years time. What would you have wished you’d written down? Also make sure you have committed an appropriate amount of time to complete this - it shouldn’t be an afterthought and is as important as the actual model equation.

Questions to ask:

• What are the key elements of your model build project that you need to write down?
• How will you manage version control and reference datasets and code?
• What is your approval process to ensure documentation is complete and makes sense?

Last week: what can go wrong... and what will you do about it?

Next week: opening up the watch