5 Best Practices to Visually Document SuiteScripts
Visually depicting the scripts and creating hierarchical diagrams help you to create comprehensive documentation that people of varying levels of technical experience can understand. Script documentation in NetSuite is critical for business continuity and improvement. However, script documentation is rarely developed and when it is, it is very difficult for anyone to understand. A long text document requires the reader to visualize and track the information about the script in their minds, which can be very difficult. Consequently, businesses have a very hard time fixing and improving their scripts. Our clients have found it very useful to have some script information depicted as visual diagrams. It enables them to see how the script fits into the process from a business perspective and then drill down into more detailed levels to understand the nuts and bolts of how it works.
- Align to processes: Scripts are encapsulations of your business processes. Documenting a script in the context of the business process provides useful information for anyone trying to work with it.
- Break it up in to different levels: Don’t try to document everything in one diagram. We have found it very effective to define different levels of documentation. A Level 1 diagram provides the process context at a high level. A Level 3 diagram would show how a person interacts with the system. A level 4 diagram shows how the scripts and functions interact. This enables a business user to understand and validate the process down to Level 3. The IT staff and developers can then drill down into more detailed diagrams, while understanding the process context.
- Swim lanes can represent people, the system, scripts or functions: Depending on the level of detail you are mapping, the swim lanes can represent different things. At a higher level they can represent the type of script (eg Server Scripts or, more specifically Before Submit scripts - see diagram above) as a whole with multiple scripts being triggered by that role. This keeps the document easy to read for non-technical audiences. At more detailed levels the swim lanes can represent individual scripts or even functions and the work they do.
- Capture details in text: Some information, such as the purpose of the script, is better described using text. Instead of cluttering a visual diagram with text, drill down and provide reference documents that are linked to the visual swim lane diagrams.
- Validate with stakeholders: Since you now have multiple level documentation that can be understood by IT staff, developers and business users.