Four tips on Anaplan model documentation
Author: Timmy Thomas is a Senior Anaplan Model Builder at Autodesk, Inc.
Documentation within Anaplan may seem like a mundane topic, but it is crucial to the long-term success and vitality of an Anaplan model. Inevitably, there will be change management to deal with throughout a successful model’s lifespan. Whether the model experiences new power users, new model builders, new business requirements, or all of the above, accurate and thorough documentation will allow new and experienced end users alike to have a successful model use experience.
Working as the primary model builder and/or solution architect for a model often causes the Anaplanner performing the work to feel as if the model is intuitive. However, if you have ever started a new position or project requiring you to quickly learn a model built by someone else, you know that even the best built models can be quite confusing to newcomers. Having solid, detailed documentation explaining the purpose of the model can save hours, if not days, of productivity time, as it provides a guidebook of sorts to tune the focus of the newcomer.
With this in mind, we will be diving into some best practices for model documentation. Please note that Anaplan model documentation is naturally not a one-size-fits-all solution. Models of different sizes and complexities will require different solutions. There are a million different ways to document, from media type to specific software solutions. Keep this in mind as some of these approaches may or may not work for your specific use case.
Documentation is a team effort first and foremost. All of these tips and guidelines were developed by the amazing Anaplan team at Autodesk. A special shout-out to Senior Anaplan Model Builder Nicole Johnson (@nicole.johnson), whose documentation expertise and knowledge has heavily informed this article and has set up the team for sustainable success! Let’s get started…
Anaplan documentation best practices
1. Clear naming conventions
While naming conventions may not immediately jump to mind as belonging to the domain of documentation, it acts as the foundation for succinct, efficient documentation. Make sure your model’s modules, lists, line items, actions, etc. follow a consistent and easy-to-understand naming convention standard.
A good example of a solid naming convention standard is starting each module name with a prefix of its DISCO functional area followed by a numerical indicator. Why the numerical indicator? Our team has found that including this number is a quick and easy way to point out module names without having to type out the entire title. For example, from the following screenshot, if I’m writing documentation to point the reader to the module SYS12, I only need to write “SYS12” rather than “SYS Time Filter User Selections [PY-2, 11, Q] PY-2 to CY+7.” This saves time, simplifies, and reduces confusion. It also makes documentation much more readable.
2. Utilize the native Notes feature
An often-overlooked feature Anaplan boasts is the “Notes” section, which is available in almost every area of the model within the modeling UX: Versions, Lists, Modules, individual Line Items, Line Item Subsets, Actions, etc. all contain the ability to add notes. These notes help model builders and/or end users understand the purpose of various individual components of the model. Even if a line item or module’s purpose seems obvious, taking an extra minute to type out what its function is can save lots of time down the road.
Because the notes section is not displayed prominently, it is often not used at all. However, a well-documented model with notes attached to each component can make it significantly more auditable and sustainable, and thus, meeting best practices. Just because a formula seems obvious to one model builder does not mean that a model builder with a fresh perspective will be able to easily understand it. Please note that while the Notes feature is very helpful, it is constrained by a character limit of 250. So, while it can be great for quick explanations and pointing to additional resources, it is best used in conjunction with other documentation techniques.
3. Use a specific documentation platform
While there are great uses for the Notes feature, robust model documentation needs at least one additional platform. This would be somewhere where you would explain larger concepts of the model. You can also point out module dependencies, explain the model’s calendar, list model stakeholders, etc. This should be thought of as the model’s “guide” which can be used to teach a new model builder what they need to know about the model’s purpose. This allows a layout to be built that makes logical sense to follow, so that those new to the model have a structured way to learn rather than jumping into the model and attempting to trace out calculations to figure out how things are working.
Wiki software often works well for this type of platform, but there are countless options to choose from depending on what works best for your team. The key to a successful documentation platform is a thoughtful layout combined with consistent updates. When these two objectives are adhered to, you end up with a clear platform that is easy to use and helpful to all those on the team – as well as new teammates in the future! See the following screenshot for a good example of a well put together model Wiki table of contents.
4. Steady, frequent updates
Potentially the simplest best practice, but also the easiest to forget about, is keeping your documentation up to date. Once you have established practices and platforms for your documentation, all that’s left to do is to make sure it stays current and relevant to the model’s use case. A good model adapts to ever-changing business requirements and so, by necessity, will go through many large changes and enhancements over the years of its use. Its documentation must follow suit, or else it will become outdated and useless over time.
As a model builder, it is difficult to take the extra time during development to make sure what is being built is accurately captured. However, it doesn’t have to be painful! Try some of these approaches to build good documentation habits into your schedule without it becoming overbearing:
- Schedule a “Documentation Day”: Oftentimes, you may be working through critical tickets and simply do not have the time to document your work as you go if you want to meet a deadline. That’s okay! To ensure that you still document your work, consider scheduling specific time on your calendar for documentation. If it’s once per month, perhaps you need a half day. If your cadence is more frequent (such as weekly), maybe you only need to schedule an hour. Set aside specific time to hold yourself accountable!
- Build in “buffer time” for documentation on each ticket: If working within a ticketing system like JIRA or Asana, make sure to overestimate the time it will take you to complete a ticket by an extra ~30 mins to give yourself the necessary time to document your work.
- Peer reviews: Every ~6 months, have someone on your team who is less familiar with the project/model you are working on review your documentation and make sure that they can follow what you’ve done from a high level. If there are missing pieces, it should be obvious to them, and having this standing review time helps keep model builders accountable!
Just like with everything else Anaplan related, this isn’t a one-size-fits-all solution. Pick and choose which approach works best for you and your team.
Conclusion
There are many other best practices to be followed when considering documentation for your Anaplan solution. Hopefully this provides a good starting point to make sure your models are documented and kept both auditable and sustainable. Following these guidelines will help you ensure that your Anaplan implementation is set up for success both in the near- and long-term future. Remember that not all of these practices will work for every team.
Experiment with different approaches to see what works best for you and your team. It may take some time to find the right balance, but once it clicks then your team should get into a comfortable rhythm of documentation upkeep.
Happy Anaplanning and documenting! Leave a comment with your documentation tips!
Comments
-
@TimothyThomas - I really like this suggestion of a documentation day! It is so easy to let things get "stale" and then it feels like a huge undertaking to bring everything back in order. Incorporating documentation as a part of your sprint schedule would be a way to keep it at the top of the radar!
2 -
Excellent tips @TimothyThomas ! This was perfect timing for me as I am embarking on major documentation phase. Thank you!
1 -
Thanks @Tiffany.Rice & @jziemer for the kind words! Glad this could be of some use!! Let me know if anyone else has additional documentation tips 😊
0 -
@TimothyThomas When we start building modules we start with specific sequence and end till specific sequence…let's say if we are building Revenue & Cost model → we start with volume, total cost per item, Price and final output as Total cost & Revenue. (INP01 Volume plan, INP02 cost input,INP03 Price input, CAL01 Revenue, CAL02 Cost)
When we are in middle of development, there may be a client requirement to break this cost input into Material, Manufacturing and Distribution… So in this case how do you number the modules?
Option 1: INP01 Volume plan, INP02 cost input (delete), INP03 Price input, INP04 Material, INP05 Mfg Cost, INP06 Distribution cost, CAL01 Revenue, CAL02 Cost
Option 2: INP01 Volume plan, INP02 Material,INP03 MFG Cost, INP04 Distribution cost, INP05 Price input, CAL01 Revenue, CAL02 Cost
In option 1 I've deleted cost module and created new modules at the end, in this option if some one sees the module list there will be missing sequence number INP02
In option 2 we've deleted cost module and created new modules in the middle of sequence and renamed all subsequent modules (This is time consuming but here there will be no missing sequence)
This is a common challenge when we start giving numbers to modules
V.Sai Bharadwaj
1 -
Really good point @Sai_Bharadwaj_Venati ! It's a great call-out. This can definitely cause headaches, especially in situations where you need to adjust a process buildout that was done long ago.
The way we deal with this is that we don't necessarily number our modules to be sequential. While this could potentially be seen as not the most logical approach, we find that it saves us time and still works in the long run. For our team, the numbering system is really just for nomenclature purposes. Even though we will have, for example, an INP11 and INP12 module, that doesn't necessarily mean that INP12 is next in the input process after INP11.
Often it will be built this way, but if we were to go back and need another input module "between" INP11 and INP12, we would just name it INP13 even if within the model logic it isn't necessarily following the input in INP12.
This way also, when inevitably models become more complex throughout their lifecycle, we don't have to change a bunch of modules' numbering just because we're adding something new to the foundation of the model.
That's just how we prefer to do it - but also understand your method. It introduces challenges as you mentioned, but at the same time it can be useful to have the numbering be more logically sequential.
Thanks for the comment!
1 -
Thanks for clarification. @TimothyThomas.
One documentation tip: -
From end user POV ⇒ Once entire model goes live, we record the screens explaining what is the screen, why it is required and how to effectively use it and we record these screens category wise (ex:- volume, Price, Revenue, costs etc.). These recordings are then shared to client and whenever there is a change, we would create additional recording explaining what we changed and why that is required.
Same concept can be applied to Documentation as well. Create a recording explaining the content in Version 0 of the user manual/ wiki and subsequently explain the changes in recording. These recordings can be done on documentation day
This process of recording screens/ notes or anything helps as change trail and users can understand what is there is Version 0 and what additional changes done in Version 1
V.Sai Bharadwaj
0
