by Andrej Byrtus (ERNI Slovakia)
What’s the worst that could realistically happen after taking over a new project? One can never truly know. That’s why preparation and a thorough transfer process is necessary to cover as much ground as possible when taking on the responsibility for maintaining the next solution.
But then again, processes, processes, processes… It is almost tiring at times to keep in mind all the formal steps that need to be taken in order to finish a task. This might be a long-standing issue of some of those processes existing just for the sake of existing. Let’s take a look at how to perform project handovers and their maintenance with some examples of which areas to focus on and explain why having a plan to lean on is crucial for success.
The journey begins at the end
As per the definition of the SDLC (Software Development Lifecycle), the end marks the beginning of our process – maintenance.
In an ideal scenario, the team that developed a solution will also be the team that takes care of its maintenance and further development. This is not always the case, as can be inferred from the need for these maintenance guidelines.
For a better overview, it is possible to split the knowledge that needs to be documented or transferred into several topics. Some of them are self-explanatory in nature and some might have hidden caveats.
1. Domain Overview
2. Permissions and Access
3. Environments
4. Development & Operation
5. Tools
6. Contacts
7. SLA
8. Long-Term Plans
Domain overview
Domain experts are crucial for analysing difficult topics and issues which might arise as a result of daily operations or ever-changing external factors. But this is a numbers game, and statistics do not lie when they tell us that difficult issues are fairly rare.
That’s why it is possible to focus on the essentials when onboarding new stakeholders and still succeed. A vertical slice through the solution is the perfect onboarding tool. Begin with the ‘why’ and follow up with the ‘how’.
Let’s say we are taking over a bee monitoring system.
- Why does the solution exist?
Beekeepers were tired of daily trips to the farms to check up on the health and status of their hives.
- How does the solution resolve the problem?
By providing a remotely available monitoring dashboard with real-time images and sensor data, the cost of trips was reduced, fewer were made and critical issues could be caught in time.
Through this kind of description, even an outsider can quickly become familiar with the topic and has some basic knowledge to refer to when working with any part of the solution.
Environments
There will be established environments where each holds its own purpose. Development and production are taken for granted, but what about anything in between?
As some solutions are more difficult to set up locally, it is often necessary to prepare a shared testing environment that’s used exclusively by the developers and maintainers of the solution. It might be tempting to later reuse it for customer tests, but this has some real downsides. Among these downsides is the inevitable conflict and confusion.
The tasks of different stakeholders cannot always be parallelised. If tests are being performed in the same environment that is intended for investigation of production issues, a time will come when these two align and one of the parties involved will need to back down. If neither can because of resource allocation constraints – most commonly time – a conflict is born.
This could have been avoided by better communication and management of what exactly is being done and when. But why create extra work overhead, when it can be completely avoided by having separate environments? The value they bring by creating an uninterrupted development and testing environment is very often worth the costs. This also serves to raise awareness of this one of a multitude of responsibilities carried by project maintainers – they do not only maintain what exists but also review which parts can be either expanded or consolidated.
Development and operation
Distinguishing between guides of greater and lesser importance will never be possible with 100% reliability. Balancing the effort necessary to maintain such guides and the value they provide can be very tricky. What a good development and operation guide should contain are instructions for repeated tasks that adhere to some form of checklist.
Even if you have already become familiar with a project or have been working on it since the conception phase, you will find that not having to keep a mental map of all the obscure or rare tasks can be very helpful. Not just to improve your productivity, but also to relieve yourself of the burden of holding all the information.
For our example with beekeeping, what would be some repeated tasks that adhere to a strict plan and could be written down? These could range from feeding processes to health management or even how to winterise a hive.
Identifying useful information
The tried and true approach to crafting a great guide is to put yourself into the shoes of a newcomer. If you ask yourself “Would I be able to recreate it given these tools and documentation?” and the answer is anything but a confident “yes”, there is definitely something missing.
More eyes are always better in this case. In a lot of cases, people involved in a project already do write documentation for their own needs. Having a common gathering point for this knowledge is the last missing step. Instead of just asking around for how to do XYZ and then doing it, reserving just a few minutes to document could be all that’s standing between wasteful practices and stress-free maintenance.
Just another WIKI?
The main difference between some of the established documents that pertain to project development and the aforementioned strategy for documenting topics is formality. Documentation maintainers are often constrained by a multitude of tight definitions, usually coming from strict standards or other project guidelines. Most of the critical information and guides already exist in some form or another – one only needs to have a proper guidebook where they can be put.
If you would like to explore the theoretical foundations behind this topic, read also our previous Techletter Application of the Fourier Transform in data preparation for AI: Beyond the time domain.