Response to Elphaba

Sage
Posts: 1,232
Joined: 2002.10
Post: #1
Elphaba,

If my reply in the previous thread came across as condescending, I apologize. I really am interested in improving the quality of Apple's documentation, and in teaching developers how to use the OpenGL API efficiently.

OpenGL is complicated, and confusing documentation doesn't make it any easier. However, official documentation is written using the vocabulary of the API, and a chapter of specific optimization tips must assume familiarity with those terms.

As you pointed out, the purpose of these forums is to share knowledge. On many previous occasions, I have explained how OpenGL works at great length. One example relevant to this topic is about multitexturing. In particular, the paragraph about accessing vertex attributes based on the current state shows a real-world example of using a constant attribute.

That said, a curt reply like "read the documentation" is still a valid reply. Worrying about optimizing out constant attributes is a case of premature optimization for a "Newbie" developer.
Quote this message in a reply
Member
Posts: 749
Joined: 2003.01
Post: #2
Its pretty clear to me that an example is often much better understood than more abstract documentation.

Like in math to understand a more general theorem you often think of a specific case to get a feeling of whats going on.

try to get started with cocoa or some other complex library starting from the documentation without sample code, it's a dauntingly hard task.

©h€ck øut µy stuƒƒ åt ragdollsoft.com
New game in development Rubber Ninjas - Mac Games Downloads
Quote this message in a reply
DoG
Moderator
Posts: 869
Joined: 2003.01
Post: #3
Examples don't have the capability to cover all the caveats that documentation can, as the docs are supposed to contain all the "but if" cases, while an example will always just showcase something very specific.

Neither sample code nor documentation is usually sufficient on their own.

Also, that math analogy is just wrong Smile A lot of higher math has no immediate way of visualization, such as calculus with complex numbers. You *can* visualize and create examples of how it works with the subset of real numbers, but that only covers a tiny fraction of what it is all about.
Quote this message in a reply
Member
Posts: 749
Joined: 2003.01
Post: #4
DoG Wrote:Also, that math analogy is just wrong Smile A lot of higher math has no immediate way of visualization, such as calculus with complex numbers. You *can* visualize and create examples of how it works with the subset of real numbers, but that only covers a tiny fraction of what it is all about.

I didn't say anything about "visualization".

©h€ck øut µy stuƒƒ åt ragdollsoft.com
New game in development Rubber Ninjas - Mac Games Downloads
Quote this message in a reply
DoG
Moderator
Posts: 869
Joined: 2003.01
Post: #5
You just said "to understand a more general theorem you often think of a specific case to get a feeling of whats going on," which is often the very wrong thing to do. s/visualization/think of a specific case/ if you will.
Quote this message in a reply
Member
Posts: 749
Joined: 2003.01
Post: #6
Well, Since i don't manage to immediately grasp theorems in their whole generality and implications abstracting from any specific case like you do, i used to initially get a feeling thinking of some specific examples.

Now i finally know it's THE very wrong thing to do, i apologise.

©h€ck øut µy stuƒƒ åt ragdollsoft.com
New game in development Rubber Ninjas - Mac Games Downloads
Quote this message in a reply
Member
Posts: 260
Joined: 2005.05
Post: #7
Najdorf Wrote:Well, Since i don't manage to immediately grasp theorems in their whole generality and implications abstracting from any specific case like you do, i used to initially get a feeling thinking of some specific examples.

Now i finally know it's THE very wrong thing to do, i apologise.
IMHO, there isn't anything wrong at all with that. Documentation and examples should go together. Good, very focused examples are wonderful to get a good idea about the principle, and then you can go from there to the detailed documentation, or in the case of theory, to the formal definitions.

I love small, focused examples, and I love making them. The smaller the better. The more irrelevant stuff I can take out, the better it gets. They do not give the whole picture, a demo showing how to put a button in a window doesn't cover the whole range of possibilities, but it gives you a digestable start.

Speaking of theory, I think it works there too, as long as you don't limit yourself to that simplified example.

I think DoG means that you can't only have those examples, which is quite correct. You should not stop there, but you can start there.
Quote this message in a reply
Post Reply 

Possibly Related Threads...
Thread: Author Replies: Views: Last Post
  This Collision Detection/Response Tutorial... MacFiend 13 5,324 Sep 24, 2003 01:19 PM
Last Post: MacFiend