1.1. Debugging Cookbook
The debugging cookbook is a workflow designed to help you fix any problems you will encounter while going through this project but it is applicable to any problems you will encounter throughout your life. It can be summarized as a 5-step process:
Frame the Problem
Read the manual
Ask google.com
Ask chatGPT.com
The concept is to optimise the gathering of relevant information while minimising the cost and time spent to gather it. Therefore, you should always try the quickest option first and then invest more energy getting a relevant answer.
1.1.1. Frame the Problem
This step is the most crucial and the most difficult one, before you try to fix any problem, you need to be able to frame it clearly:
What are you trying to fix?
What do you know works?
What should work but doesn’t?
What behavior is it giving instead?
Then you must ask:
What is the purest way to express it?
And only then can you ask:
How do you fix it?
Once you have properly framed the problem, you must simplify it down to the key blocking element that you don’t understand while removing all the things that work as intended. This is well spent time as it will highlight the precise pain point you’re going through and will amplify the quality of the search results, saving you much more time in the long run.
Always keep in mind that you are wasting your time if you try to fix a problem that you either don’t clearly understand or that you didn’t fully simplify.
1.1.2. Read the Manual
The manual, the datasheet, the website’s documentation or the FAQ should always be the first thing you go to as it is a tailor made explanation of the exact problems you will encounter while doing what you are currently doing and it is written by the most knowledgeable person in the world: the person who designed the tool!
95% of problems can be fixed by simply reading the manual but so few people actually start there that the internet has developed an acronym for it: RTFM.
In the case of the microver.ch project, the manual is the website that you are currently reading: docs.microver.ch. You will find a search bar at the top left of the documentation, make sure to use it regularly by typing in it the 1-2 keywords that you are searching for as the website will browse every page it has and provide you with a list of relevant pages where that word appears.
Figure 1.1.2: Search bar of docs.microver.ch
You won’t find any information more relevant than this one as it is expertly written specifically for building a microver! In addition to the general information on the website, you will find specific information (datasheets, 3D models, images) about every single component inside our kits by visiting the Core Parts resource:
You will also find a guide about the tools you will need to use and how to use them correctly on the Key Tools page:
1.1.3. Ask google.com
Even the best documentation in the world can’t regroup all possible error cases and this is where the internet can be a very powerful tool.
Figure 1.1.3: Search bar of google.com
Forums are a goldmine of information as people all around the world post their errors. Here are some of the best forums for engineering :
But the internet isn’t limited to forums as it will also parse all the html documentation written by other people for their own projects. Whether on their website or on forums like Discourse which regroup user comments around a project.
It is for those reasons that we recommend starting with the internet before going to Artificial Intelligence as you are getting direct human (often expert) written information about a specific topic inside a coherent community. In this sense, the information quality is as good as when you “Read the Manual” but here the manual isn’t written specifically for your project.
Therefore, to look up information on the internet, you should try to include a bit more context than when looking inside the manual. While limiting the amount of words to the 5-8 key words that other people could also stumble upon if they were to get your error.
1.1.4. Ask chatGPT.com
If you found some information on the internet but don’t exactly understand how to apply it to your problem or you need a more detailed explanation, this is where artificial intelligence models like chatGPT really shine.
Figure 1.1.4: Search bar of chatGPT.com
These Large Language Models (LLMs) are trained on as much data as physically possible, usually scraped from the web (not always legally). So they first develop a deep understanding for the correlation between words and then, they are fine tuned to respond to a user’s prompt in a helpful manner. This turns them into a superpowered tool for re-explaining, adapting or further developing solutions already on the internet, almost like a personal tutor with infinite knowledge, time and patience.
Please explain to me, in a simpler manner, the following concept
that I just found out about:
The downside to this tutor is that they have a little too much ego to admit that they don’t know what you’re asking them about and so they prefer making something up than telling you that they don’t know the answer. Over the years, they have gotten excellent at making people believe that they are really smart and so they will trick you with their hallucinations.
“Hallucinations” are how we call the “made up” information that these models invent when they are pushed further than their training dataset. This is why you should always fall back to the internet for quality information, for example by asking the models to cite their results:
Search the internet to cite me 3 sources for the information you
just output.
1.1.5. Ask a Knowledgable Person
The only thing better than a “personal tutor with infinite knownledge, time and patience” is a human tutor with limited knowledge, limited time and limited patience but a real capacity to reason and modesty to admit that they know nothing about the subject at hand.
In the case of our project, this is where the Discord Forum comes into play! Of course, always use the search bar before asking a new question:
Figure 1.1.5: Search bar of forum.microver.ch
This is where your mentors, teachers and expert friends excel. The only reason that these people aren’t higher up the list is because their time is highly limited and more importantly, because relying on someone much more knowledgeable than ourselves when learning something new risks losing all of our autonomy.
Indeed, it is much more efficient to ask for help every baby step of the way as the answers we will receive are undoubtedly much better than if we were to try by ourselves. So, we save time and money by not working on the wrong solution and it is much less painful than trying alone, isn’t that a win-win?
No, the issue with this method is that we don’t learn by being told the right answer by somebody more knowledgeable, we learn by smacking right into the wall really hard after trying for days. That’s the kind of learning that sticks with you for years, the learning that actually makes you better in the long run, the one we all yearn to obtain but so few of us are willing to put in the energy to deserve.
Please signal any mistake to: errata@microver.ch