模型技术文档的最佳实践

ArunThakar
4月11日编辑 博客
Technical_Documentation_BestPractices.jpg

作者:Arun Thakar,注册规划师和银行业副总裁。

随着上线方法的临近以及管理员和最终用户培训的临近,“我们如何记录模型?”这可能是你日常单口相声的首要和中心问题。不要害怕!本文将介绍其中的一些关于文档的最佳实践以及如何利用它来确保采用,并揭开您的团队在过去几个月里花费了大量时间开发的一些复杂建模特性的神秘面纱。

本文主要有三个要点。首先,利用系统设置菜单和模块Blueprint中的notes列。其次,位于anplan之外的文档可以作为一个很好的参考,帮助用户快速确定他们需要查看哪个模块或列表来找到答案。第三,创建简单且易于阅读的架构图,在高层次上给出模型组件的感觉,以支持并将您的技术文档联系在一起。让我们进一步展开:

  1. 为所有关键的计算、操作和列表使用注释列来创建模型内文档。这允许您的超级用户和系统管理员调试、理解和增强模型,而无需参考外部文档或咨询原始模型构建器。在读者审阅代码之前,一个好的注释会描述公式试图做什么。注释在注释行项创建背后的业务原因或体系结构决策时特别有用。关于操作的注释,特别是那些在流程上使用的注释,可以为集成管理员节省时间,因为集成管理员试图理解导入的作用,而不必深入研究操作菜单中的不同选项卡。
  2. 模型之外的参考文档便于管理员进行导航。在创建文档时,无论是文本还是幻灯片,最好有明确的受众。技术文档应该有图表,并关注模型的组件,让读者了解数据是如何流动的。对于技术文档,最好从文档要完成的内容、目标受众是谁以及文档范围之外的内容开始。概述还应该有一个高级模型架构图。技术文档的其他组件可以包括数据管理和转换、列表、模块和操作的摘要、计算深度、集成摘要和用户体验概述。下面是对这些部分的描述:
    1. 数据管理和转换。这里是读者理解源数据格式和数据来源的地方。它也是一个展示数据如何从源格式转换为规划人员与之交互的多维数据集的地方
    2. 列表、模块和操作的摘要。现在,您可以利用添加到系统设置菜单中的所有描述性注释。创建每个包含关键列表、模块和操作的表,并添加更多关于它们如何与业务上下文相适应以及在何处使用它们的上下文。
    3. 计算潜水。您的特定计算逻辑应该被清楚地定义,以防有人询问模型是如何计算度量的。用概念性定义来展示幻灯片要比打开模块蓝图并在公式中混来混去容易得多。这里的流程图添加了有价值的信息,推荐使用。
    4. 集成。表在记录集成时很有帮助。最好将表分成几组,比如入站表或出站表,或者按数据源或目标表。
    5. UX概述和功能。考虑到用户体验可能发生变化,不建议编写详尽的用户体验文档。相反,最佳做法是为每个板或工作表设置一个页面,并附带一个大小合适的截图。与每个板相关的文本不应该包含建模考虑,但绝对应该包含板的目的和关键功能。试着用项目符号标注细节,并在屏幕截图上绘制标注。
      最后需要注意的是,文档不应该教管理员如何建模构建,而是可以将有疑问的管理员重定向到诸如Anapedia和Anaplan支持以及贵公司的卓越中心。
  3. 图是表达模型架构的最佳方式。以下是一些创建图表的最佳技巧:
    1. 确保图表易于阅读。如果您发现自己在流程图中绘制了太多的线和框,那么您可能需要将其提高到一个粒度级别。详细的原理图只有在解决方案架构师将它们呈现给观众并且能够浏览图表时才有用。
    2. 将模块分组在一起以突出功能。例如,您可以将图例作为模型的功能区域,并在列中创建流程图迪斯科框架,查看系统菜单中的模型映射功能(在功能区级别),并尝试跟踪从数据分段模块,通过计算一直到报告和输出模块的功能。
    3. 使用合适的粒度级别。概览架构图不必是特定于模块的,但应该是介于功能区域之间的某个地方,并详细说明关键的功能组件。
      如果读者有一个图表来支持技术文档的数据转换和集成的每个部分,以及每个深入的部分,这可能会有所帮助。当你有了一份草稿文件时,在交接之前与听众进行交流是很有帮助的,以防他们有问题,因为这将帮助你根据他们的知识空白来调整内容。

关于技术文档,您会添加哪些最佳实践?留下评论吧!

评论