Author: Lucas Charello is a Community Captain and Senior Board Consultant at Kiwika.
Hello, Community! My name is Lucas Charello, and I’ve been working at Kiwika for almost three years as a Senior Board Consultant and Project manager. Today, I’m excited to bring up a big topic that is sometimes overlooked: The importance of documentation during the delivery process and how this helps to drive the project to a long-term success. More specifically, having a good Bill of Delivery document will be the difference between a smooth and error-proof deployment and a problematic and unreliable one. It also may be the difference between having a good or a bad relationship with a customer.
So, imagine this quite common situation: You and your coworkers spent weeks or months creating new features or a whole new module in your dev environment. You went through all necessary testing, everything works and visuals look good. Now comes the critical time of deploying all that hard work for the first round of testers, and that task is assigned to you alone. The delivery is due in a few days, and the customer wants to reduce application downtime as much as possible as they constantly need to use the application etc.
Well, at this point you remember you didn’t have good visibility about the work done by your coworkers, and it’s been a while since the last time you made a deployment. Depending on your experience level and your coworker's discipline in documentation, this can feel like a challenging situation. Hopefully, you and your coworkers agreed to consistently fill a “Bill of Delivery,” and it will be your path to a stress-free deployment!
A Bill of Delivery can be an official deliverable document containing all details about a delivery, or it can be made and used internally for organizational purposes. As different companies may have different requirements when defining official documents, here we will focus on non-official organizational purposes. A good Bill of Delivery will drastically reduce the chances of error during implementation and optimize the application downtime.
From this perspective, the Bill of Delivery I suggest using is composed of:
- A general summary describing the whole go-live process, naming each step in a simple and understandable way.
- Specific sections explaining each of those steps in detail. Some steps are standard, and others may change every time the document is used.
- One or multiple “Deployment procedures” created directly inside the concerned BOARD application. Those procedures will be responsible for reliably creating data in the other instances of Board.
- All the previous points should be organized in a chronological way so they can be used as a step-by-step procedure.
- A header, generally on the first page, describing the scope and the author(s) of the document.
Some of those topics may need a deeper dive—here we go:
Topic number three can use a deeper explanation for beginners: The main tool we have for deployment, the “ALM Transporter package”, is used to create data structures inside one database of the instance in which we deploy. Ex: Cubes, Procedures, Data Readers, etc. However, new cubes and entities will be empty in the new instance. If you need key cubes or key entities to be populated, you have two choices:
- Manually populate the structures. This may be adapted if a very low volume of manual operations is needed. Example: A single member should be added to an already existing key entity. If you use this method, you must document it very well. It’s QUITE easy to forget this kind of step during a massive deployment.
- Create one or more “Deployment procedures” containing Data Readers and Dataflows. The sole purpose of those procedures will be to populate cubes and entities during the next few deployments. It’s especially useful when deploying several entities and/or several key setup cubes. They can be capsule procedures or database procedures. Always remember to test those procedures prior to a delivery. I like to name them “Deployment procedure_Projet Name”.
Quick tip 1: I use Deployment procedures as much as I can because I simply love the fact that I can have one of the most important parts of a deployment done by only clicking a button! I populate my key setup cubes and entities via a deployment procedure since the very first time I use them in the dev instance. In that way I kill two birds with one stone: The cube is populated, and the procedure is tested.
Quick tip 2: I prefer to build my deployment procedures as Capsule procedures. I make them inside a Test capsule so I can easily move between instances without a problem. In this way it’s easier to deploy as we don’t need to make a DB Transporter.
Topic number four: The chronological order could vary following companies’ best practices. Here is an example that works for me, along with some specific information:
- Header.
- Summary.
- Deployment preparation: Everything you should do before the deployment. This step revolves around Backups. Capsule backups, DB backups, where to store them, etc.
- Deployment: This is the moment in which you will be pulling the strings inside Board, so do not save words: Explain all steps as well as you can! I would always mention the following sections as well as the order in which they should be performed:
- What to do before setting up the Transporter. Ex: Deployment procedures, transferring text files, etc.
- Transporter Package setup: What to check or uncheck when creating the Transporter Package.
- Transporter Package execution: When to launch it in chronological order.
- Capsule delivery: Which capsules and when you should deliver them.
- Deployment Procedures: When to launch them and in which order.
- Manual data creation: When to do it.
- Actions after executing the Transporter Package. It can contain Deployment procedures, visual verifications that entities are populated, checking screens, etc.
- Any other action or commentary that could guide the deployment.
- Application reset. Sometimes it’s necessary to restart the Board Engine and Board Web Application and synchronize User definitions to Data Model to ensure that the application is running fine after a delivery. Some people prefer to do it right after the transporter, some do it after finishing the whole deployment phase. Refer to your expert about your company best practices.
If you and your team can put together all the points above, I can guarantee that your deliveries will be quick, smooth, and clean! I can tell it’s a real relief to open this kind of document to see that all the team has been disciplined and precise in their instructions. The perfect situation is when this document is completed collectively during the devs. In that way, the instructions are as specific and pertinent as possible. If some pieces are lacking during its first use, it’s also good to complete and proof the document during the deployment in the Test environment (s2 or other) so it will be the perfect path for a smooth deployment in Production (c1).
This article is all about removing obstacles during a deployment using documentation. The Bill of Delivery generates a win-win situation where the time spent writing instructions compensates for the time we may lose during a deployment and diminishes our reliance on human memory only. Also, the moments in which we are under pressure are the ones where we are most likely to have our memory failing. It’s also a win-win for the customer as errors and downtime are reduced.
Of course, this is not a complete nor a perfect guide. If you need more help with this subject or just if it interests you, please feel free to contact me. Also, I’m sure there is room for improvements in the guidelines I propose.
What do you do differently? Please share below so I can learn from you as well!
__________________________________________________________________________________
You might also like:
Moving forward with an insider's lookback
Customer Success: Enabling strategic pathways to drive optimal results
‘Run as administrator’ feature: What you need know
___________________________________________________________________________________
