Apple's Documentation: Awesome, Far From Flawless
I know liking documentation makes you pretty old school. We‘re supposed to just bump along the road, looking up every obtuse error on google and finding other Mr. Toad‘s who happened onto the same road. One of the great things about documentation is that it often tells you in advance what you can expect, and what the framework will expect of you, saving you a TON of time stupidly guessing, piecing together clues left instead of guidance by lazy programmers.
When Apple rolled out CollectionViews at WWDC 2012, the project lead Olivier was flailing his arms and sputtering so much, I was half expecting that in addition to being able to make a bookshelf for documents in your own apps with a few lines of code, that the compiler was going to being forth the swaddling Baby Jesus as part of a 6.0/Second Coming Double Bill. Mind you, I have been writing/using grid components for a LONG time, and love collection views, and the demos are awesome, but sadly, my experience of the docs is that they‘ve fallen and can‘t get up.
Charge #1: how on earth do you finally deliver a real grid and not have a demo that shows the three quintessential things all iOS developers have been wanting for ages??:
- The ability to show a collection of documents on a bookshelf
- The ability to show stacks of items in piles, with animations as they go in and out of those piles (c.f. Mail and iPhoto)
- A coverflow browser
Not only is the sample code (usually a huge strong suit) truly anemic, as you crawl down into the ape suit to get these things yourself, the aid you are given is so paltry (especially compared to the arrival hype) that it made me feel a tad bit like Google had sent over some moles to destroy the productive capacity at Apple.
Case in point: you would think that making a bookshelf would be a small matter of dropping a wallpaper behind the items, as a first step. There are zero wallpapers out there for the iPad, to show anything. There are a few for the iPhone.
Then, when I got into the guide, I thought ‘oh ok, shame on me, RTFM (again in this case)‘ but in fact, there‘s just not that much there, and what is there is confusing and contradictory. On the one hand, the guide tells you that you can subclass the layout class, but that you really shouldn‘t have to, then coordinating images to be a background requires said subclassing! Yes, that‘s right. I scoured the IB menus because I thought for sure it‘s just going to be set this view‘s background image. Nope. Then I found a LONG thread discussing this that is McGyver Meets Murder She Wrote. Ok, on this point, I found that you can do self.collectionView.backgroundColor = [UIColor … But then the cells are just sitting on top of an image. Do do something more you will have to subclass.
It‘s not that that‘s the worst thing in the world. What I am complaining about is when you create something around which a massive amount of consensus has coagulated over decades, just provide the expected things. Don‘t come and show sizzling demos and tell people it‘s going to be easy. Furthermore, the ringmaster in the WWDC sessions said ‘we can‘t wait to see the amazing layouts you all come up with‘ so many times, he made Anthony Robbins seem like Calvin Cooledge. Dude, how ‘bout you just deliver the 3 or 4 that would cover 90% of uses and make them wireable from Interface Builder, then we‘ll give you an A without you having to stroke our self-esteem.
Hope this is not an omen of things to come. I still believe Apple has such a commanding lead on Google in the tools arena, that it would take the equivalent of a cerebral hemorrhage to have it dissipate, but weirder things have happened (more on that). In the meantime, please, for the love of god, rectify this mess, Folks.