Documentation: It Starts With the 'Why'

PhilippErkinger

Documentation is one word that gives most model builders a cold shiver. It’s associated with binders full of information lost in archives or the output of rushed efforts to complete an implementation. 

As an Anaplan partner, we come across a bandwidth of different approaches to Anaplan model documentation. Let's discuss our learnings and best practices to keep a balance between the effort put into documentation and its actual value.

It Starts With the 'Why'

Before diving into the details, ask yourself what the purpose of your model documentation is. Why are you doing it? In our experience, there are only two reasons: transparency and the communication of thoughts.

1. Communication of thoughts. The majority of documentation is created to communicate a certain thought, like a user guide that describes to the end-users how a dashboard was thought to be used. Yet, keeping it simple is an art. It always helps to have your audience in mind. What are they interested in? How relevant are certain details to them? And always ask: is it easier to create a sketch or video instead of text?
2. Creating transparency. As a model builder, you will make hundreds of decisions during an implementation project. Some may only be relevant to your peer model builders, like why did you use a numbered list instead of a normal one. Other decisions might have a significant impact on your business model. For example, how are drivers used to calculate revenue projections? Documenting decisions increase the transparency for your end-users. Transparency is fundamental for trust.

Documentation or Diary?

We have experienced implementations where the entire documentation is written in a great hurry at the end of a project. During this time, model builders will try to recall decisions that were made weeks or even months ago. This kind of documentation is mostly ending up in an archive folder simply because it lacks relevance and often doesn’t contribute to transparency.

A best practice is to see documentation like a diary. It should be part of your daily routine. When you create a new process, use the notes field (see below) to describe what this process does. Even if you take over a model and you are unsure if a process is used, make a note! There are also fantastic tools like Coda that help you collect the daily thoughts of an entire project team. The key is to create a culture where you document daily and in small, simple but structured steps.

Architectural Maps

Maps are amazing tools. They help you navigate through your solution or process. Tools like PowerPoint or even a simple flipchart are perfect to create maps that explain the flow of a process or a high-level architecture. Other tools, like Lucidchart allow solution architects even to create interactive tools that let you zoom in and out of a map. The key is to keep them simple and understandable. Don’t try to add too many layers!

Anaplan has also a built-in model map (see below)

that shows you how modules are connected. A fantastic tool for someone that wants to get an understanding of how a model is build up. To make it valuable, each functional area should only contain a limited number of modules. For example, a functional area called SALES may grow over time to include 40 modules focusing on several different processes. This makes the business map difficult to use. In this case, it is better to split the functional area into smaller areas focused on individual planning processes within the sales department, like SALES – ONLINE or SALES – B2B.

User Guides

The most common type of documentation is user guides. Yet, it is also the type that is mostly forgotten in a drawer and never updated. Think about the Windows 95 operating manual, a masterpiece with several hundreds of pages. Some end-users read the whole book, others gave up after three pages. At least it was relevant for three years until Windows 98 was released. Today, the pace of new software releases is significantly higher. When building an Anaplan model, you may release new features in a weekly cadence. This makes it a massive endeavor to keep user guides alive and relevant.

Instead of writing user guides, we advise using platform features (like the description fields on a dashboard) to provide hints and tips to end-users on how to use a card on a board. Also, text fields can be used to describe the purpose of a dashboard. With images, you can even add process flows to dashboards showing, for example, the end-user “you are here” in a process map.

Training Videos

Videos and recordings can be great tools to communicate thoughts. They are particularly powerful when you want to offer on-demand training for new Anaplan users. Let’s say, for example, your company has 300 sales reps where some are leaving and others are joining on a regular basis. All of them need to deliver a sales forecast at the end of the month. Getting all of them into regular training is almost impossible. Short videos for different topics can help to get their attention and keep them up to speed with the tool. This could also be a perfect tool to communicate release notes on a regular basis. Just try to keep them focused! You may also discuss with their managers to make these videos part of their start-up training.

Technical Documentation

The greatest style variation is generally found with technical documentation written by model builders for model builders. We have seen a lot, from one-pager sketches describing an entire model to detailed Excel lists explaining every single line item and formula and even custom build scripts using DAG methods.

In some instances, legal requirements dictate the level of technical documentation, but these situations are very seldom. Instead, the driving factor is mostly the personal skill set or the corporate culture. Ultimately, it should be the technical Anaplan skills of the model builder team that dictates the required level of detail. A Master Anaplanner won’t necessarily need an explanation of formulas or model structures, yet it may be relevant for them to understand the overall business logic and architectural design. A model builder with less experience may need more help, but the additional information could be found through Anapedia or the Anaplan Community (yes, that’s also documentation).

Keeping a Balance

Creating valuable documentation is not rocket science, but it is easy to get out of balance. The following principles help you to develop model documentation that communicates your thoughts and ensures transparency:

• Communicate with your users.
• Start simple, expand when needed.
• Keep it relevant, when things change.
• Make it part of your daily routine.

And as you may realize, it’s the same guiding principles as for Anaplan model building. Starting with “why” and following these guiding principles will help you to create valuable documentation without much effort. Happy documenting!

MaySA

Very interesting and informative article! 🙂

abhay.kanik

Amazing Content @PhilippErkinger . Never thought Documentation can be explained this well.

Cheers!

sosunkwo

Great article. I learned a few things. I like the idea of thinking of it as a diary. Thanks for sharing. 

jb.neel

Fully agree, documentation is essential. It must be clear and simple to be used, it must be dynamic to live as Anaplan models live… It is for end users, but model builders deserve something as well to control the huge Anaplan power !

nicarter

Nice article @PhilippErkinger - it sounds like you have been listing to our conversations saying 'we need to capture the Why, not necessarily the What'. Ensuring adequate time for documentation as part of any sprint is critical - what if the key model builder won the lottery tomorrow - how do we ensure knowledge isn't lost for the organization? 🤑

Notes and Tooltips in Anaplan are definitely a helpful feature, as are dedicated dashboards to provide guidance to both users and administrators alike. Personally, I think that the more documentation that can be centralised in the Anaplan platform the better - it provides a seamless experience and helps business teams drive efficiency. 

Frequently we hyperlink to Wiki/Confluence pages, or videos to provide additional materials if necessary. As these are cloud-based, they can be updated easily.