15 Data Science Documentation Best Practices

There’s no single data science project documentation recipe. Rather, your documentation needs will vary by project, team, organization, and industry.

And it’s not just about producing data science model documentation. Instead, think broader and ask – What do I need to document and why?

Once you’ve thought this through and have goals in place, you can then set a repeatable plan for how to document a data science project.

Guiding Principles

Let’s start with three guiding principles.

1. Document with a purpose

Before you build out your documentation, ask:

• Who will consume this documentation?
• Why do they need this documentation?
• How would they like to consume documentation?

Think broadly and don’t take a “one-size-fits-all” approach. Rather, you should create various artifacts that best serve each set of stakeholder’s needs.

13. Build user documentation

Don’t forget your users! Rather, be sure they know how to use your system.

If you have a user interface, a great practice is to put a help menu link in the upper right of your screen so that the user can navigate to find items such as:

• How do I control the visualization?
• What are the definitions for key measures and dimensions?
• When is the system available?
• Where do I report a bug or request a product feature?

Another common output for a model is via an API. In this case, write technical documentation so that the receiving-end engineers can build on top of your API. Include items such as definitions, endpoints, parameters, data formats, and response times.

Data Science Project Documentation Templates

14. Grab a pre-built template

There are a few templates that can help get you started.

• CRISP-DM:CRISP-DM is the most common data science life cycle and defines a series of documents you should develop throughout a data mining project. Warning – these documents tend toward a more traditional view of extensive documentation, and (given CRISP’s age) the CRISP-DM guide lacks modern deployment best practices. You can visit Patiegm’s Github page for a handy CRISP-DM documentation template.
• Microsoft’s TDSP: Microsoft takes a more modern documentation approach in its Team Data Science Process. The Charter and Exit Report are particularly useful, even if you do not use TDSP.
• Model Cards: In a 2019 research paper, Google introduced the concept of a Model Card to set a vision for standardized and transparent model reporting. Visit withgoogle.com for an overview.
• Data Science Checklist: Checklists are a great way to identify what needs to be done and to track the status of each task. As such, consider our data science project checklist.

15. Build your own data science documentation template

The reality is that your project, team, and organizational needs will deviate from the above templates. As such, use these as starting points toward creating your own data science documentation templates.

Congrats! You made it to the end. But your work is just getting started. Remember that these data science project documentation best practices do not apply to all circumstances. And your situation will likely require some additional practices not mentioned here. So to review:

• Know your audience
• Keep it simple but not too simple
• Document your plan
• Document your model
• Document your system
• Build and customize your own templates

Best of luck and reach out if you have some additional pointers you found useful.