This is a general programming issue, not a system programming issue. Not so long ago at work, I had to implement a regex search over a Lucene document store. Now, the thing is that we used the latest version (at the time) of Lucene, 3.0. All the examples I found online and most of the documentation referred to version 2. Naturally they didn't mentioned they were using version 2, I just had to scratch my head a few times while I tried to realize why the regex API depicted there is not only different, but not even merely existing. Turns out one of the design goals of Lucene 3 was to separate stuff from the core Lucene to external libraries. So, after finally searching through their SVN I found the source files for the regex libraries. I ran into some problems with the way Lucene parses regex queries and relates it to terms and again, as in the article, after hours and hours of searching through documentation I resorted to just reading through Lucene's code, which indeed turned to be fruitful for less the time I invested in finding and reading documentation...
I really was not sure what to learn from that episode. The logical conclusion seems to be to try to read your way through the target source code, if you have it, before investing the time to find and skim through documentation. On the other hand, it feels like a really bad lesson.
Time will tell if this moral holds up.
I've had this go both ways before, too. I think the point to take away from this sort of experience is that the best you can do is apply your best judgment and re-evaluate as you go along. Often opaque documentation makes sense after you gain some context by reading the source; it works the other way, too. With experience, you gain a sense for what path to go down; sometimes that (subconscious) heuristic is totally wrong, which is why it's important to consciously re-evaluate on top of that. The current approach isn't making you any practical headway, even though you're learning a lot about the system in question? Take a step back and try looking at the bigger picture; what are you really missing? If you can, sleep on it for a bit.
Most of all, if you're getting it right more than 50% of the time (and I'm finding it hard to imagine a way you'd do worse than that) there really is no point beating yourself up about it.
I really was not sure what to learn from that episode. The logical conclusion seems to be to try to read your way through the target source code, if you have it, before investing the time to find and skim through documentation. On the other hand, it feels like a really bad lesson. Time will tell if this moral holds up.