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!
