If you've played any of the BioShock games you've probably noticed the really goofy tutorial messages that pop up at nonsensical times. Like, you'll be in the final boss fight and you'll be getting messages that let you know how to crouch. The game doesn't seem to have any sense behind what help it offers or when it's offered.
This is annoying and distracting at times, but maybe it's better than the situation where a player might return to a game after taking a couple of weeks off and not realizing they've forgotten half the controls. It's bad enough if you can't remember which button throws a grenade, but it's even worse if you forget about the grenades entirely and you hit a part of the game designed around the grenade mechanic.
So I think what BioShock is trying to do is kind of admirable, it's just a bit heavy-handed and clueless about it. It sucks needing to replay the tutorial just to be reminded of the basic controls. This is especially true today when tutorials are integrated with the game and re-doing the tutorial means sitting through forty minutes of cutscenes, loading screens, exposition, and hand-holding, and so it's nice if a game can ease you into things without stopping the fun.
I had a background in programming before I began complaining about videogames for a living, and I found it interesting how complex this problem is when you really sit down and think about how it should work.
Let's assume your goal is to make a system that will dispense hints when the player needs them and avoid dispensing hints when they player doesn't need them. For the purposes of this exercise, a confused player with no help is just as serious a failure as a player who is being shown information they already know. Our goal is to make a system to remind you of controls when you actually need a reminder but otherwise leave you alone and not spam your screen like a version of Clippy with a gun fetish.
Remember that as a programmer you can't have the program "offer help when the player appears to be stuck" because the program has no idea what "being stuck" looks like. You have to figure out what "stuck" means, and you have to write the rules to figure out if its happening. The heart of the task is in figuring out when they need the help.
We need some kind of system for tracking player actions. We need to track when they sprint, jump, crouch, switch weapons, reload, climb ladders, use items, use special abilities, take cover, etc. We need to divide the mechanics into distinct concepts and track how often players demonstrate mastery of a subject. For the purposes of this system, we need to make a point of intentional player actions. If the player hits the change weapon key, we count it as a demonstration that they know how to use that system. If they auto-change weapons due to picking up a new one or running out of ammo on another one, this weapon switch shouldn't count.
Popup hints should stick to input mechanics. Avoid mixing tactical help (ice monsters are vulnerable to fire spells) with mechanical help (press X to select spells) because they're two different types of information and should be presented in different ways. The tactical help can be provided in-character because it's part of the world. The input information is there to explain things that the player character should already know how to do. Duke Nukem already knows how to jump, we just need to make sure the player knows how to tell Duke to jump. Master Chief already knows how to reload a gun, the player just needs to know which button to use to make it happen.