Best practices for technical documentation of a model

ArunThakar
ArunThakar
edited April 2023 in Blog
Technical_Documentation_BestPractices.jpg

Author: Arun Thakar, Certified Master Anaplanner and Vice President in the banking industry.

As go-live approaches and admin and end user training gears up, the question of ‘how do we document the model?’ might be front and center in your daily standups. Fear not! This article will cover some of the best practices on documentation, how it can be leveraged to ensure adoption, and demystify some of the complex modeling features your team has spent so much time developing over the last few months.

There are three main takeaways from this article. First, leverage the notes column in the system settings menus and module Blueprint. Second, documents living outside Anaplan can be a good reference for users to quickly identify which module or list they need to look at to find answers. Third, create simple and easy-to-read architecture diagrams which give a sense of the model components at a high level to bolster and tie together your technical document. Let’s expand on each of these more:

  1. Use the notes column for all critical calculations, actions, and lists to create in-model documentation. This allows your super users and system admins to debug, understand, and enhance the model without having to refer to an outside document or consult the original model builder. A good note will describe what the formula is trying to do before the reader reviews the code. Notes are especially helpful when they comment on the business reason or architecture decision behind the line item’s creation. Notes on actions, particularly those used on processes can save time for integration admins who are trying to decode what an import does without having to dive deeply into the different tabs in the actions menu.
  2. A reference document outside the model facilitates navigation for admins. When creating a document, whether its text or slides, it’s good to have a clear audience. Technical documents should have diagrams and focus on the components of the model to give the reader a sense of how data flows. For technical documentation it’s good to start with context about what the document is meant to accomplish, who the intended audience is, and what is out of scope for the document. An overview should have a high-level model architecture diagram as well. Other components of technical documentation can include data administration and transformations, summary of lists, modules, and actions, calculation deep-dives, integration summary, and UX overviews. Below are each of these sections described:
    1. Data administration and transformation. Here is where the reader goes to understand the source data format and where the data is coming from. It's also a place to show how the data gets transformed from its source format into a dimensionalized data set which planners interact with
    2. Summaries of lists, modules, and actions. Now is your chance to leverage all those descriptive notes you added to the system settings menus. Create tables each containing the critical lists, module, and actions, and add more context on how these fit in with the business context and where these are used.
    3. Calculation deep-dives. Your specific calculation logic should be clearly defined in case someone asks how the model is calculating metrics. It’s much easier to present a slide with a conceptual definition that opening the module blueprint and muddling through the formulas. Flow charts here add valuable information and are recommended.
    4. Integrations. Tables are helpful when documenting integrations. It is a good idea to split the tables into sets such as inbound or outbound, or by data source or target.
    5. UX overview and features. Given that the UX is likely to change, exhaustive documentation on UX is not advisable. Instead, a page for each board or worksheet with a good-sized screenshot is best practice. The text associated with each board should not contain modeling considerations but should absolutely contain the purpose of the board and key features. Try bulleting the features with details and drawing callouts to the screenshot.
      One last note, documentation shouldn't teach admins how to model build but can redirect admins who have questions to resources such as Anapedia and Anaplan Support, as well as your company’s Center of Excellence.
  3. Diagraming is the best way to convey model architecture. Here are a few best tips for creating a diagram:
    1. Make sure the diagram is easy to read. If you find yourself drawing too many lines and boxes in the flow chart, you might want to take it up a level of granularity. Detailed schematics are helpful only if the solution architect is presenting them to an audience and can walk through the diagram.
    2. Group modules together to highlight functionality. You could, for example, make your legend the functional areas of the model and create the flow chart in columns as the DISCO framework, review the model map feature in the system menu (at the functional area level) and try to trace the functionality from data staging modules, through the calculations all the way to the reporting and output modules.
    3. Use the right level of granularity. An overview architecture diagram doesn't have to be module specific, but should rather be somewhere between the functional areas with specifics on critical functional components.
      It might be helpful for readers to have a diagram supporting each section of the technical document for data transformation and integration, as well as in each of the deep dive sections. When you have a draft document, it’s helpful to socialize it with the audience before handover in case they have questions, as this will help you tailor the content to their gaps in knowledge.

What best practices would you add regarding technical documentation? Leave a comment!

Tagged:

Comments

Categories