navas@cory.Berkeley.EDU (David C. Navas) (06/18/91)
In my opinion, this belongs in .advocacy, so I have set the FollowUp-To there. In article <22523@cbmvax.commodore.com> peter@cbmvax.commodore.com (Peter Cherna) writes: >Be serious, the documentation specification can be finalized long before >the last significant code changes. Ah, so we should all expect 2.0 documentation before the ROMs? As in "long before?" I guess I won't hold my breath for 2.0 ROMs then... The main beef that I have with the documentation is two fold. The RKMs are perfect reference manuals. In fact when I first taught myself the Amiga's kernel, I printed out the includes (this was back in '86). You see, I lived way back in the boonies where we were lucky to have a dealer (who later went under), nevermind access either to documentation or even information about such documentation. This does in no way change the fact that the RKMs are perfectly INADEQUATE for learning the Amiga's OS. You see, I had a good deal to go on with those includes, but the thing that taught me the OS was *EXAMPLE CODE* that was *documented*. In particular fastdir by Dave Haynie taught me all the things I didn't want to know about DOS, and some triangle rotating program which was written by someone whos name slips the mind. At least the 2.0 Autodocs have a little more code here and there.... Under unix, it's pretty easy to experiment with function calls -- if you get them wrong, you core dump. If you get an Amiga program wrong, your system reboots. Makes the learning curve a bit more frustrating. On an A3000, that's okay, on an A500 where you're developing out of RAM, it's a might unacceptable.... In essence, then, we need a couple of goal-oriented type documentation. I realize AmigaMail is supposed to help here, but AmigaMail is too little too infrequently IMHO. I'd rather pay you folks a moderate sum for a weekly publication or something like that. In fact, I'd rather pay a lump sum and get the whole thing in a book. Anybody that could, for instance, explain the iffparse.library to me.... Of course, if I had source to the Display program, no one would need to (I assume). That's probably the argument in these circles. Although, to be perfectly fair, it must be noted that Cmdre *does* release source for a number of programs in their DevCon disks. *I* would rather have a manual, but it is better than nothing. Secondly, books are written by third parties to fill in these gaps. BUT when push comes to shove, Cmdre can always say, "but that manual wasn't written by *us*. We can't help it if it has incorrect or misleading information." You see? I want a manual that tells me how to program the OS the way YOU envision that it ought to be programmed. That's not to say that you restrict us to one method, rather you give us a working method that we can start with. We can then consult the RKM's when we want to change a feature or two. >We guarantee the functional and structural interface, not the implementation. >Therefore, it is entirely natural that we publish the former, and not >make the latter available. Perfectly acceptable. I want good documentation, though. By the by, you could write a book comparing the Amiga OS's programming methodology to other system models, give good points and bad points and lots of example code written for different systems (Mac, Windows, Xt/Unix, etc.). It's a bit of advocacy, it would point out the weak parts of your own OS to you, and it would benefit at least one developer that I know :) David Navas navas@cory.berkeley.edu 2.0 :: "You can't have your cake and eat it too." Also try c186br@holden, c260-ay@ara and c184-ap@torus