Why is this necessary though? The newer, more recent articles (emphasis on newer as in I am not talking about the hook documentation) are pretty well done. I'm speaking from my own perspective of course which is one that comes with zero background in php. But with the documentation I've learned how to use the valuable functions in IPSmember, how to use modal popups, how to make userhovercards, how to use lightbox (and grouping lightboxes!!), how to use autocomplete (with custom databases, I've wanted this since content 2.0), how to display an error and what code number to use, how to manipulate the page title and even add on to the breadcrumbs, how to add to the head (you know the entire article on outputting html is perfect by itself), and how bitwise works (I'm never going to try it but at least I know how it works). What Brandon (and whoever else is working on it, just Brandon's name is sticking out in all the articles I read) is doing with the developer documentation is, I feel, on the right track. The only thing I might have an issue with is the organization of things, but that might be a personal issue. I can't even navigate my way through the marketplace...that and examples, but Brandon said we can use comments to ask for those now.
Just throwing a suggestion out there: wikify the dev articles? As in, allow seasoned developers (several of whom have commented above) to actively take part in editing the articles. The edits don't have to be applied immediately, but can be reviewed, e.g. by bfarber and whoever else is in charge overall with those. Sure, there's the commenting system, but I think that developers would be more encouraged to develop the articles if given a more active part in writing them.
I'm not trying to suck up, I'm being sincere. In reading the articles that've only popped up over the past month I've learned a lot about IPB and PHP too. Admittedly the only one I've really implemented is ipsmember and the error code one for my hook, but I would've never been able to make that only hook that I've released without those articles. I think with just a little more patience the entire developer documentation will be quite useful.
Although I can agree with you a little...I'd love it if Michael could (and would) contribute to the documentation. I recall after reading one explanation from him I learned everything about using data hooks and his hook making walkthrough was incredibly useful.
So I think in the end I made a big post about nothing. That's ok. It's 1 am and I can't sleep.