Process Documentation Standard in FLODocs

Transcription

1 Process Documentation Standard in FLODocs Contents Purpose of this Document Documentation Structure Level 1 Top Level Level 2 Overview Diagrams Level 3 Operational Processes Level 4 Detailed Script Interactions Level 5 Metacode December 30, 2014 Purpose of this Document FLODocs customers document their processes in FLODocs to enable their operational and IT staff and any future consultants to quickly understand the processes and their relationships to NetSuite customizations. This document provides examples of how processes are documented within NetSuite. This document is not a replacement for training in using FLODocs to produce each type of documentation. It should also be understood that these examples are guidelines. The purpose of a document is to Process Documentation Standard in FLODocs Page 1 of 13

2 communicate effectively with the target audience to the level of granularity required to address the business need. The main levels of documentation are broken out into sections of this document and they each contain the following: Audience: Who the documentation is designed for Objective: The purpose of the documentation and what it is intending to accomplish : How that level is represented in a Swim Lane or HLP (High Level Process) Diagram : How process details are captured in that level The detailed steps of how to do these things in FLODocs are documented in the FLODocs FAQ, which is accessible from the FLODocs tab in NetSuite. Documentation Structure The process documents within FLODocs have the following structure. Figure 1 Process Documentation Structure in FLODocs High Level Process Diagram (#1): The High Level Process Diagram Template depicts the complete process picture from end to end, which helps us understand how the entire organization works. Essentially, this is the road map for the person reading the document. The numbered process boxes help the reader know where they are within the process itself as they go into the more detailed portions of the document. Each process shown on the High Level Map can be supported by more detailed information in the and Process Swim Lane Diagram. These numbered documents describe the next Process Documentation Standard in FLODocs Page 2 of 13

3 level of detail below the High Level Process, so that you can quickly see what part of the High Level Process Diagram they reference. (#2 ): The is a step by step wizard that is designed to enable any user, regardless of process management skills to document a process. You can use the Assistant to create High Level Diagrams and Swim Lane Diagrams. The Assistant is also where the detailed process information is managed such as: a. Work Instructions: You can document detailed process information in the Add Details section of the. This enables users to drill down and find detailed information without cluttering up the diagrams. b. Links to Customizations: Since FLODocs is in NetSuite, process steps can be linked to the FLO Customization Records, which are automatically updated by the FLODocs Spider. The FLO Customization is a meta record of the NetSuite customization that is created by the spidering process. Links to other customizations and processes are captured and managed in this record. c. Links to Standard Operating Procedures (SOP) : Use SOP as your most detailed documents that describe specific steps an employee can use to execute the process. SOP s document screen shots and fields if systems are used, as well as other information required to complete the step. Other process documents can include job aids, tip sheets, and checklists to ensure consistent execution. Process Swim Lane Diagram (#3): The Process Swim Lane Diagram Template shows the steps in the process by using swim lanes. The swim lanes represent roles, people, or groups in a company. Boxes represent tasks with lines connecting them to show how the process moves forward. When you are developing one for the first time, the swim lane diagram can be automatically generated from the Jot Down Steps step in the. High Level Process Diagram (#4): You can decompose a box on a High Level Process Diagram into another (second) High Level Process Diagram, instead of only using the detailed process documents. Then, you can again decompose this second High Level Process Diagram into the more detailed process documents, such as the Swim Lane Diagram, or another High Level Process Diagram. By linking these different types of documents, you can describe large and complex process systems with very simple tools. Level 1 Top Level Audience: General Objective: Provide a high level view of the complete process library, provide context for the processes and enable users to navigate to specific processes. Process Documentation Standard in FLODocs Page 3 of 13

4 The High Level Process Diagram depicts the main process groupings across the top with sub processes listed below. The processes do not need to be in any exact order or sequence since they will occur based on different triggers and timing. The placement is for general reference. Document the name and a brief description of the process at this level for reference. Figure 1 Top Level Processes Level 2 Overview Diagrams Audience: General Objective: Represents specific instances of an end to end process or the major substeps under a process. FLODocs supports different views of a process to represent specific versions or iterations of a general process within the documentation. For example, it may be desirable to show each of a set of order to cash processes within a common framework. In some cases, entire processes, such as payment Process Documentation Standard in FLODocs Page 4 of 13

5 processing, might occur in each path, whereas other parts of the process may only leverage a limited number of common elements such as distinct sub processes. In these cases we can developed a particular form of HLP diagram, called Overview Diagrams to reflect different ways transactions can occur. These Overview Diagrams appear at the top of the high level process column alongside the common high level processes that appear in one or more of the specific process flows described in the overview. In the example below, the Order To Cash and Procure to Pay processes are laid out as generic processes. As an example, the first process under Procure to Pay is the PTP Overview. Within the PTP Overview, specific variations of PTP processes are depicted. Generic Top Level processes may be included in a specific process flow as appropriate to the specific procurement type. The connections between processes are depicted as parent and child relationships within FLODocs. A given subprocess may have multiple parents representing the different processes to which it belongs. Purchase Requisitions is a child of Procure to Pay since it is a sub process of that larger process. Within PTP Overview (See figure 3) that same Receive Orders is a child of Inventory, Parts and other processes since it is applicable to those type of procurement processes. It is excluded from others such as Supplies. In this way someone can see specifically how the PTP process is different between different procurement types. When a process is displayed within its main parent, it is numbered simply by the last part of its number. For example, Process 3.3 Purchase Requisitions appears on the Top Level Diagram with the label (3 Purchase Requisitions). When it is attached to another parent with a different numbering scheme, it shows it s full number ( Purchase Requisitions). A process appearing at multiple places in a diagram is still a single record ensuring that any changes to the process are visible in all relevant documentation. If someone were to click on Purchase Requisition from the Top Level diagram or any of the processes in the PTP Overview marked Purchase Requisition, they would go to the same or Swim Lane diagram as appropriate. Any changes made within the Swim Lane Diagram or Process Assistant would therefore impact all of the other Purchase Requisition documents. This also applies to the numbering and title of the box itself. The numbering is maintained so you can identify which processes are the same. Process steps that have a different primary parent are slightly greyed and cannot be edited other than through the. Process Documentation Standard in FLODocs Page 5 of 13

6 If a particular flow requires a different Purchase Requisition process, a new and separate process should be created for that process. Figure 3 PTP Overview NOTE ABOUT ORDERING MULTI PARENT PROCESSES: By default, processes are listed in a high level process in numerical order under their parent. This order can be altered, however, by simply dragging the processes into a different order. Once established, the non default order will govern. Multiple processes can be selected and moved by dragging the mouse over all relevant processes. Only processes completely within the selection area will be selected. Document the name and a brief description of the process at this level for reference. NOTE ABOUT SETTING MULTIPLE PARENTS: A process can be assigned multiple parents in the. Process Documentation Standard in FLODocs Page 6 of 13

7 Level 3 Operational Processes Audience: Process users and IT Staff Objective: Shows the steps and actions required by departments, stakeholders and systems to execute a process. This depicts user and script/ workflow interactions and appropriate. It should be at a level of detail that is understandable to both business and IT teams. Guidelines: The details of the relevant scripts should be stored in the process assistant. Script and workflow elements should be represented by generic swim lanes representing types of automation: i. Client Scripts ii. Server Scripts iii. Suitelet iv. Scheduled Script The work instructions store general descriptions of the role of each script in the process. Due to the complex nature of scripts and workflows, we have developed the following standards for documenting them in FLODocs based on the level of detail being viewed. System and human interface: When a user is working with the system, the scripts or workflows can be depicted as a role or swim lane the swim lane diagram (See Diagram 5). Scripts and workflows should be documented if they are actually doing work within the process. If customizations are referenced, they can be highlighted in the Add Details tab of the. If there are multiple scripts or workflows they can all be grouped in a swim lane called Scripts or System to facilitate documentation. To find out about that specific customization, the user can drill further in it. Process Documentation Standard in FLODocs Page 7 of 13

8 Figure 4 Example Swim Lane with Scripts Documented In the example above, if the user drilled down into 2. Complete Line Item, they would see the a Detailed Script Interaction diagram (described further in the next section). If desired, this diagram could also be depicted as a Metacode diagram (also described below). When multiple scripts are involved, however, Metacode should be avoided. Linking Customizations to Processes Customization records can be linked to process steps. This enables analysis to understand what customization are used in a particular process. At this level, the attached customizations should represent the entire script or workflow. You can also include any specific fields, searches or records relevant to the steps represented. The level of detail should match the detail of the diagram. The customization can be linked in the in the Add Details tab (See Figure 5) Process Documentation Standard in FLODocs Page 8 of 13

9 Figure 5 Customizations in Processes and customizations can also be linked in the FLO Customization Record to enable analysis of what process steps are associated with that customization. Describing Script and Workflow functionality Where a step represents the operation of a script or workflow, the can also be used to describe what the script or workflow does in the process. The objective is not to recreate the code in a written format or to describe it at a level of detail better suited to a deeper level of diagram, but to enable someone to understand what it is supposed to do. In the cases when calculations occur, it is very helpful to describe the equation so someone reading it knows what elements are involved and how. This also provides useful documentation at this level in cases where the next level of documentation has not been or will not be prepared. This information should be documented in the overview for that step, which can be found in the Jot Down Steps tab of the. We have adopted the following approach for documenting scripts and workflows. Processes or steps that represent a script are documented in the following way: Script Name of Script : Description Process Documentation Standard in FLODocs Page 9 of 13

10 Figure 6 Example of Script Documentation Overview Processes or steps that represent a workflow are documented in the following way: WF Name of Workflow : Description Figure 7 Example of Workflow Documentation Overview Level 4 Detailed Script Interactions Audience: Process owner, IT (can also be used to validate code logic with business sponsor / process owner) Objective: This level of documentation provides a detailed description of the interactions between script elements and people, to a mid level of detail. At this level individual scripts are assigned their own swim lanes and take on the role as actors. Guidelines: These are usually appropriate to describe processes with interactions between no more than 5 different actors (roles or scripts) and can be useful in describing the interrelationships between scripts. Inputs and outputs can be described in labels associated with the diagram but are preferably described in the overview or work instructions. The work instructions provide an overview of script logic. This need not be overly detailed but is intended to provide a general understanding of what the script is doing to a level of detail that will not be affected by small changes to the underlying logic. Process Documentation Standard in FLODocs Page 10 of 13

11 The swim lanes at this level are primarily separate scripts, which are identified by name. This is particularly useful for documenting interactions between scripts. Where instead there is a single complex script with numerous functions, the swim lanes can be functions. Where functions are used, the name should be followed by brackets (ie () ) to identify the lane as a function not a script. Where multiple similar scripts or functions fulfill the same general purpose, they can be grouped in a single swim lane as it the case here. Figure 8 Example of Detailed Script Flow with swim lanes based on functions. Where the swim lanes are scripts, each step would normally correspond to a function or a functional path within a function governed by a condition. The overview will contain a brief description of the logic of the script with reference to any functions. If greater detail is required in respect of a step, it can be entered in the work instructions. Where the swim lanes are functions, the individual steps would summarize the logic of the functional path within that function but be above the level of metacode. For example, in the above example, the Send to All and Send to Reps processes hide the complexity of the underlying metacode, rendering the diagram easier to read. The customizations relevant to each step can be attached using the Add Detail step in the Process Assistant. This will make it much easier to quickly identify the specific customizations relevant to each step and, conversely, the business or code logic related to each customization. Level 5 Metacode Audience: Primarily IT Process Documentation Standard in FLODocs Page 11 of 13

12 Objective: This level of documentation provides a detailed description of how the code operates. It is used to document the logic of a particular existing or planned script. The functions are usually represented by swim lanes. Detailed documentation of the relevant fields and related objects are stored at the script customization record. Guidance: Description of these elements should only be to the extent necessary to make the documentation understandable and consistent with the objectives of the business. In many cases, it may be preferable to internally document the code since this will be extracted onto the FLO Customization record. The swim lanes at this level can be functions if applicable or can be a single swim lane if the document is below the functional level. Each step at this level represents a portion of the internal logic of the code. Effort should be made to ensure that that steps are at the same level of complexity and represent the business logic flow rather than the programming control logic such as null value tests, error controls and other code that represents good programming practice but would overly complicate the diagram. Moreover, shared objects, such as functions called in multiple contexts should be documented as processes to avoid duplication of effort. Figure 9 Example of FIrst Level of Metacode Process Documentation Standard in FLODocs Page 12 of 13

13 Figure 13 Bottom level of metacode The overview of each step should expand upon the step name. Any detailed logic of greater specificity should be detailed in the work instructions, if necessary to understand the document. For example, the formula for calculating the GP% can be set out in the Overview. More complex descriptions of logic, if required would be set out in the Work Instructions / Description. Both appear in print view. Process Documentation Standard in FLODocs Page 13 of 13