can be defined as spending a great deal of time trying to use something properly, (as defined and recommended by the official documentation,) only to discover that the formerly preferred method of doing something is now recommended against and actively discouraged.

this particular example has to do with Core Animation layer hierarchies. which are documented (poorly) as a proper way to go about doing a certain task. however in the more recent update to the developer documentation is the following little tidbit: