The Amazing Invisible Documentation!

Discussion in 'General Mac Discussion' started by awrc, Aug 7, 2002.

  1. awrc macrumors regular

    Joined:
    Apr 20, 2002
    Location:
    Milwaukee, WI
    #1
    Reading these boards, I've seen the subject of Cocoa vs Carbon, and the relative paucity of native Cocoa apps vs Carbonized apps, raised quite a few times.

    "Why," the questioners ask, "don't more developers write pure Cocoa applications?"

    Back when I was just a guy with a PC, I'd wondered about this myself. I'd done a reasonable amount of coding with Win32 and MFC and generally liked developing for the platform, although I found much of the UI coding to be clunky and tiresome (which are the same words I'd used to describe writing UI code for X/Motif five years earlier).

    So, when I bought a PowerMac in February, I dived headfiirst into Objective-C and Cocoa. I was delighted by the language, and equally pleased at the way the Cocoa UI frameworks took so much off the work off the programmer's hands.

    I picked up all the books on Cocoa programming I could find (3 - two good, one bad), I read the introduction to Objective-C and Cocoa on Apple's website.

    Then I noticed something odd. On my bookshelves I had various "general" books on Win32, MFC and .NET coding - stuff like the Charles Petzold books. I also had some MCSA self-paced coursework tutorial texts. Finally, I had two extremely big sets of manuals - five volumes of Visual C++ documentation covering the language itself, the run-time, the MFC (2 volumes worth), and the standard template library. I also had an additional five volumes providing similar documentation for Win32 as a whole, including a book on the Common Controls, one on GDI, one on the base system functions and so on. Both of these sets were expensive - $150 list, $92 from somewhere like Bookpool and took up a good eighteen inches of shelf space each.

    They were not bedtime reading, they were not always accurate, but they were there. The combination of stuff like Programming Windows With MFC and Programming Windows with these reference libraries were invaluable. Anything you needed to know was in there, quite often with examples. While Microsoft don't seem to have published a similar mammoth library for .NET, take a look at the shelves in Barnes and Noble - books on every .NET related subject you can think of. I'm currently reading the .NET IL Assembler book, just for fun.

    Now, looking over at the new Mac section of my bookshelf I see two O'Reilly titles and Aaron Hillegaas' "Cocoa Programming For Mac OS X". Two of the three books are good ("Learning Cocoa" isn't). However, they're all rather slim counterparts to stuff like Programming Windows With MFC, and they're all (as you'd expect) quite focused on the GUI side of the Cocoa frameworks.

    What I also see is a huge blank space where any sort of reference materials should be. Aha, it's online, I discover. I go online, muttering unhappily (I like online documentation as a supplement to a Real Book, not as a replacement for it) and find the relevant documentation on Apple's developer site.

    Helpfully, they've separated the information into the Application and Foundation frameworks. Unhelpfully, the lists of Classes, Protocols, etc, are sorted alphabetically, which is an interesting idea when every class name starts with 'NS'.

    I then spent half an hour trying to find the exact information I needed, literally by randomly threading through the documentation until I hit the information I was looking for. On a couple of occasions (this may have been fixed since) I found missing info (literally methods that something along the lines of "To Be Written" as their description).

    So there's one possible reason for the slow rate of migration to Cocoa - once you're past the stuff the available books cover, you're thrown in at the deep-end with nothing but online documentation that's of variable quality and that isn't in an organizational framework (pun no intended) more sophisticated than that of man pages.

    I don't think it's a coincidence that the places that *are* churning out good Cocoa software are those with roots in the NeXT era. From what I can see, references titles of the sort Cocoa lacks did used to be available for NextStep at one point.

    Until Apple takes documentation seriously (and I do see this as their responsibility, it's their OS after all) Cocoa isn't going anywhere fast. I'll admit that I'm making progress - I've got half a dozen little projects at various stages of development, most of the "get familiar with the platform, not actually of much use to anybody" variety. It's ironic that while tools like Interface Builder make it possible to produce an almost fully functional interface while writing almost no application code in next to no time at all, once you get past the GUI you tend to get bogged down trying to get what you previously considered the easy bit of the code finished.

    I'll admit that some of this is my own fault - I've got a pretty good Unix background and could use the BSD layer to do the rest- but I'm determined to do it properly, using the Cocoa classes provided.

    Argh, sorry, just venting. I think it was running across a reference to my long-lost copy of De Re Atari this morning that did it. Now *that* was documentation.
     
  2. iGav macrumors G3

    Joined:
    Mar 9, 2002
    #2
    Wow that's quite a post........ ;)

    Unfortunately I'm a creative, so I have no idea what you're on about for most of it..... :(

    But I'd love to be able to learn all that stuff.... sounds most impressive....... :)
     
  3. Sun Baked macrumors G5

    Sun Baked

    Joined:
    May 19, 2002
    #3
  4. arn macrumors god

    arn

    Staff Member

    Joined:
    Apr 9, 2001
    #4
    Re: The Amazing Invisible Documentation!

    An interesting observation.

    Of note - Apple did used to be big into documention... they had an entire series of Inside Macintosh that they sold through their developer channel, and you would see many of in the bookstores. In fact, I had a few of 'em...

    I've fallen away from Mac development... so haven't kept up with the docs... but like you said, it does appear they've resorted to online docs entirely. I presume this was likely due to a combiation of two factors:

    1) lots of time being devoted to other resouces, including the development of the OS

    2) everything was changing. Things were changing from point-release to point-release. Publishing in book form wasn't probably going to very productive at this point...

    but you do give a good point... as OS X stablizes, paper documentation would be a good next step...

    arn
     
  5. tjwett macrumors 68000

    tjwett

    Joined:
    May 6, 2002
    Location:
    Brooklyn, NYC
    #5
    ha ha! same here. i'm a pixel punk/muso but i too have just started to take an interest in learning some tech stuff. i'd really like to have a go at creating an app that i need. like the perfect one for me. that would be so cool. i need an organizer/calendar type thing and if i could actually make one i'd be psyched. i have the highest respect for developers. cheers to you all, except Macromedia that is;)
     
  6. pgwalsh macrumors 68000

    pgwalsh

    Joined:
    Jun 21, 2002
    Location:
    Colorado Springs, Colorado
    #6
    Did you send a copy of your note to Apple? I would send it through as many channels as possible.
     
  7. awrc thread starter macrumors regular

    Joined:
    Apr 20, 2002
    Location:
    Milwaukee, WI
    #7
    :) No, the topic stuff in there is excellent - I'm surprised that O'Reilly haven't packaged a lot of it up the way they did some of the other Apple docs in "Learning Cocoa". Only reason I can think of is that it might suffer the same fate the stuff that ended up in "Learning Cocoa" did - by the time you get about halfway into the book it's deteriorated from a book about "Learning Cocoa" into one about copying program listings accurately.

    What I'm referring to is the stuff in the Reference Material section - that's where the real meat is, and that's the *only* place it is. It'd be great to have that on paper. It looks as though FatBrain, back in the days when they were actually FatBrain rather than Barnes & Noble, sold paper copy of this stuff, but it doesn't seem to be available. Hopefully it's the case that this is temporary, and they'll find some other place willing to sell hard copy.

    Online-only just doesn't cut it though - I'm in the habit of relaxing with tech documentation when I'm tired of sitting in front of a screen but still want to feel that I'm doing work, and I've found that it is a good way to absorb the info.
     
  8. pgwalsh macrumors 68000

    pgwalsh

    Joined:
    Jun 21, 2002
    Location:
    Colorado Springs, Colorado
    #8
    I know Kinko's will do it, but it cost an arm and a leg.
     
  9. awrc thread starter macrumors regular

    Joined:
    Apr 20, 2002
    Location:
    Milwaukee, WI
    #9
    Yeah, the prices FatBrain was selling the docs for suggested that running around to the local Kinko's was what they were doing too :)

    Thing about the Kinko's approach is that the docs are pretty heavily hyperlinked and not formatted for paper. So after you priint it out you discover it's unreadable and the thing you actually need is in another document, but you don't know where it is, just that the text is underlined :)
     
  10. balliet macrumors member

    Joined:
    Dec 21, 2001
    #10
    Re: The Amazing Invisible Documentation!

    Because most of them are porting old apps to OS X. I don't think too many developers are writing new apps intended for OS X only in Carbon.

    Well there are quite a few more Win32 programmers than nextstep programmers, and therefor, more books on the subject. I've tried to stay as far away from Win32 and MFC as I can my whole life, but from what little I've seen, I can understand why you'd need a book to learn it. Once you learn the basics of Cocoa you can almost guess how new classes are going to work. It all just makes sense. If you've read Aaron Hillegaass' book and are still having trouble understanding Cocoa, I think you need to read it again.


    I guess this is just a personal preference, but when I need to look up the arguments for a method, I don't want to go flipping through a book. I like online REFERENCE documentation.



    Take an alphabetically sorted list, prepend any given prefix to everything in the list, and its still sorted. NSArray still comes before NSDictionary despite the fact that they all start with NS.

    What exactly were you looking for? I've never had this much trouble locating something.

    I've seen that a few times, in the Cocoa Java documentation, but I don't think I've ever seen in in the Objective-C docs. Maybe I'm just lucky.

    The fact that a total rewite of an application isn't easy.

    Thats how I'd expect a reference to be. You shouldn't be reading apple's documentation expecting to learn cocoa. You use it when you already know cocoa and need to look something up. Also, I do agree with you that there aren't too many Cocoa books. More would be nice, but that isn't Apple's fault, and I'm sure they will come. You don't write a book overnight.

    Hey, if you can find some NextStep books, read them. Most of the information probably still applies.

    I don't think the Cocoa documentation is holding anyone back. Maybe the lack of books that teach cocoa, but if you know cocoa, apple's documentation is ok.

    Hehe. I've done that more than once, but I agree, learning the Cocoa way is probably the best thing to do.

    -Brian
     
  11. mymemory macrumors 68020

    mymemory

    Joined:
    May 9, 2001
    Location:
    Miami
    #11
    In my experience, just to give an example.

    I was working in some web design company as a graphic designer. After some time I was in the need/obligation to learn more about html, xml, java, etc.

    I could spend some time loking for the language I needed online, but, the best thing I did was to get a book about it. It is easy to read, easy to locate, etc. Even it wasn't the better book about it it helps a lot.

    The point is that without the apropiate OSX and Cocoa documentation on the street Apple is gonna have hard time with developers.

    If I was a programmer and I see that Apple is coming up with a brand new Unix based system totally empty of softwares for it, I would be fascinating in creatting even share ware soft to put my name in the platform before anybody else. Now, is there is not the documentation around, that will discorage me, may be Apple just want the usuas developers (Macromedia, Adobe, etc).

    So, I do think and I'm agree that Apple should focus in a real Cocoa developing campaing so many programers can jump in to the system.

    Why are you gonna sell a product with no aplicatons? OSX has less than 1/5 of the aplicatuons OS9 has, and just imagine that the lack of aplications for Macs was one of the mayor reasons why PC people didn't switch, even they where using the M$ Office.
     
  12. Hemingray macrumors 68030

    Hemingray

    Joined:
    Jan 9, 2002
    Location:
    Ha ha haaa!
    #12
    I think balliet may very well have the current MacRumors length and quote record... if Apple got its documentation from you guys, they'd have no trouble whatsoever! :p
     
  13. balliet macrumors member

    Joined:
    Dec 21, 2001
    #13
    I don't think so, most of my post is empty space between the quotes and responses. I'm willing to bet its one of alex_ant's posts in the piracy thread.

    -Brian
     
  14. boom-boom macrumors member

    Joined:
    Aug 4, 2002
    #14
    I know this maybe the slackers way of doing things but is there source code out there for these cocoa apps? I started off in the software development side of things using Pascal, the way I learnt was pooring through miles of code and going off adapting and bringing things together that I had learnt and then solving my problems. Over the years I have moved away to creating graphics, but I would like to get back to writing my own software and including some of the graphics and hey if someone else can get a little benifit from my work then it has been worth while. It seems like there is a lot of open source software out there in C and Perl but not much in the way of Cocoa. I may have been looking in the wrong place.
     
  15. awrc thread starter macrumors regular

    Joined:
    Apr 20, 2002
    Location:
    Milwaukee, WI
    #15
    Re: Re: The Amazing Invisible Documentation!

    Unrelated but possibly interesting issue - once they kill OS 9, does anybody think companies are going to start porting future versions of their apps to Cocoa, or just keeping using Carbonized code?

    Ordinarily I'd have assumed the latter to be true, simply because there's so many cases where the application is also available on Windows and a common C/C++ code base would make sense. However, the latest round of Microsoft's tools has changed things completely - I suspect we're going to see a lot more C# Windows apps (since I have to admit that C# is pretty nice) and there'll be the possibility of complete divergence of code bases. This could be rather bad for the Mac.

    It's an excellent book, but it doesn't cover everything. While you're spot-on in saying there's a certain style to Cocoa that remains consistent, most of the books focus on the GUI and document architecture - I'd like to see coverage of socket programming, for example - from the online material it appears there's some very nice stuff you can do with sockets in Cocoa, but it's very dependent on knowledge of notification centers (which is well documented) and threads (which are only documented online).

    OK, OK, I admit it, to a large extent it's a self-inflicted punishment, writing multi-threaded socket servers in any language isn't exactly a heap of fun.

    As I said above, socket code. A lot of the time taken to find this stuff arose from the fact that there's Mach message ports vs TCP/IP message ports, and that some of the nicer high-level socket handling stuff is tied seems to be tied into a bunch of other classes. It was a while before I found something that was basically just a BSD socket wrapped in an object, and by that point I'd been led astray by some of the goodies I'd seen en route :D

    Well, this is to some extent shaped by my Windows experience, where you learn the language and you learn the basics of the frameworks (or MFC, as the case may be) but you're not expected to know it all by heart - that's when you hit the reference docs.

    My ideal reference book is something like a recipe book - maybe a little more involved than the O'Reilly Cookbooks. A chapter covering each "cluster" of classes, maybe a few examples of how they're used together, that sort of thing.

    You have to start somewhere though, and while the existing Cocoa books get you off the ground, there's a "gap". It doesn't help that I'm "force-feeding" myself about eight new technologies right now while I search for a new job, and am thus trying to absorb stuff very quickly. Cocoa's not actually on my "desirable job skills" list right now, but it's more fun than most of the other stuff, so I keep coming back to it. I've only seen one job advertised locally in months that wanted Objective-C - that's because we've got GE Medical in town and it looks like they've got some legacy Nextstep stuff around. Maybe my problem is I just need to spend more time playing with it.

    I guess part of the problem is that the only books out there so far are introductory. Which is fine if you're starting Cocoa and Objective-C for the first time, but when you've got mumblemumblemumble years of programming professionally in C and C++ under your belt and are used to doing some fairly sophisticated/complex/perverse things, it's a little like Wile E. Coyote running off the end of the cliff, realizing he's standing on thin air, then plummeting into the depths. :D
     
  16. awrc thread starter macrumors regular

    Joined:
    Apr 20, 2002
    Location:
    Milwaukee, WI
    #16
    Heh, I'm sorta going the other way - coding's going to remain the way I bring in the $$$ but I've just bought a graphics tablet and ordered a book on drawing, time to see if O-grade art was the limit of my talent. I'm hoping a bit of artistic creativity will help prevent burn-out in other areas :D

    I'd like to say I'm also trying to expand musically, but so far I just review the stuff. My sole original work so far is some lyrics on an album that a friend of mine (who has probably close to a dozen albums to his name) is shopping around rather unsuccessfully at the moment. That was a horrible discovery - that I'm capable of churning out really bad lyrics (the lyrics were meant to be bad, it was part of the nature of the project) at an incredible rate.
     

Share This Page