Importance of current documentation for Board system agility and growth
Author: Harry Sun, Community Captain and Senior Purchasing Specialist at MasterPet.
We began the development and implementation of our BOARD IBP system one year ago. The BOARD Integrated Business Planning (IBP) system is highly flexible, offering users the ability to customize workflows, calculations, and various processes to meet specific needs. As business requirements evolve, BOARD can be adapted to accommodate these changes, ensuring the system remains aligned with the organization's goals. However, to fully leverage this flexibility, good documentation is crucial.
Proper documentation not only helps in understanding the system's current configurations but also serves as a guide for future modifications, making it easier for users to implement changes efficiently and effectively. Without thorough documentation, the system's adaptability may become a challenge, leading to inefficiencies or misconfigurations when adjustments are required. Investing time in detailed, up-to-date documentation is essential for maintaining the long-term effectiveness and responsiveness of the BOARD system as business needs evolve.
Looking back, we identified several issues with our documentation. If given the opportunity to redo it, we would ensure that the following aspects were thoroughly documented.
Investing time in detailed, up-to-date documentation is essential for maintaining the long-term effectiveness and responsiveness of the BOARD system as business needs evolve.
Document Entity or Cubes, Used for Admin and Control
BOARD utilizes different entity or cubes as tools to control procedures, manage different processes and achieve dynamic selection. It is important to document the function and settings for entities and cubes. For example, there is a flag you need to manually update after your financial year ends. If you forgot to update this in BOARD, you may find that certain reports and functions are not working in the new financial year.
Data Reader and Master Data Update
In our current setup, we sync all related data from our ERP system to an ODS database. Then BOARD uses SQL data reader to retrieve data from the ODS. This process ensures BOARD is always aligned with the master data in ERP. It is likely you want to categorize your data in a way where it can be easily used in BOARD. It's important to document where and how those categorizations happened.
- You may use SQL script to categorize the data while you sync from ERP to ODS. In this case, you will not find any record in BOARD system, so you need to clearly note them down in the script.
- Or, you can achieve the categorization in BOARD using data reader. In that case, you can always refer to the data reader Mapping and ETL screens to find out the details. But it's good practice to have a summary of all your data read and logics (rather than go back to each data reader to find out what logic has been implemented).
Procedure Data Flow and Calculations
Many great functions and flexibility in BOARD are achieved by different Procedures with no coding required, but there will be a lot of selections, data flow, temp cubes, and calculations. In the Procedure Edit model, you can add notes for each step in the Procedure. Make good use of the comments field. Due to the business requirement changes, you may need to add in additional steps or selections in the procedure. If you can note down why and what this step will achieve, it will be very helpful for the future development.
Utilize the Comments Design Mode
In all design mode, you can add comments. You can make the comments as pop-up comments to alert the end users. As a developer, you can also utilize the comments to highlight what filters and key values are used in this report.
You can always go the Layout view to check the data block, the calculation, logics, and filter, etc. It can be time consuming. Sometimes, you may even need to trace all the way back to the cube itself or procedure to find out what exactly those data means. If you put some simple notes in the comments, it will help you to understand how this report is constructed.
Taking down those notes while developing will bring additional workload. Continually updating notes is also tedious. But that good practice will benefit you hugely in the long run, especially for BOARD the system which is so customizable.
What other tips do you have about the importance of documentation? Share in the comments below.
Comments
-
Thank you Harry, this is really great to see as you gave some great tips and insights also reinforcing the one thing I always feel is very important which is documentation.
2 -
A few additional comments on the documentation:
Unfortunately, it is not (yet) possible to describe procedures as such--only the individual steps can be commented on. Therefore, the first step in each of my procedures is one that does nothing (e.g. ‘Wait 0:0’), but describes through the comment what the procedure is intended for (what its goal is). So another developer only needs to see this first comment to figure out the purpose of the procedure. This can also be used very well for procedure groups, for which there is (still) no commenting option.
Furthermore, other DB elements cannot (yet) be described either--there is no comment field for entities, relationships, cubes, ... in which one could describe the purpose of the object. In all our projects, we therefore currently use a procedure called ‘#DOCU#’ to describe these database elements: a procedure step ‘Extract entity’, for example, then contains the purpose of the referenced entity in its comment. The same can easily be extended to cubes, relationships, DataReaders, etc. Such documentation is also easy to keep up to date: I create an entity and the corresponding step in #DOCU# as soon as possible.
The note that such a procedure must not be executed accidentally is probably superfluous.Best,
Helmut5 -
Hi Harry, this is a great a blog highlighting the need for taking the time to add documentation during implementation. Business processes are constantly evolving. Having that documentation in built will make enhancing your Board application to meet the changing business requirements easier and faster. Having commentary to aid the end user is also a must to make the application easy for them to use. Thanks for taking the time to share your thoughts. Cheers, Kris.
1
