Re: I can't believe how complex this Format SDK is...

Tech-Archive recommends: Repair Windows Errors & Optimize Windows Performance


And frankly, I don't think I'd give higher than a "D" grade to the
concepts documentation, which I think is unbelievably badly written for
all personas except "Einstein".

Rob

I've been a programmer since '80. Done everything from embedded
controller software and micro kernels to Perl/Rexx/Shell scripting. I
remember when PC's didn't come with hard drives, and how we used to
disassemble the OS in order find places to patch a branch instruction
to force control into our disk drivers, which were nothing more than
glorified "TSR's" (for those who remember the term).

I'm really cool with "deep weeds" programming when you need to go
beyond the basics provided by the OS, and as an experience programmer
but complete "newbie" to COM, DirectX, WMF, and most of the SDKs, it
provides me with an unbiased perspective on the docs and APIs.

Overall I think the documentation is reasonably good, all things
considered....

The APIs, on the other hand, are complex, oftimes inconsistent with
many interrelated requirements and hidden "hacks." This sometimes
makes attempts to use them (Docs/APIs) frustrating and time consuming.
I've spent an enormous amount of time following medusa-like hyperlinks
through MSDN and reading a LOT of doc pages in the SDK help files often
to complete dead ends. I'm finding in many cases I'm better off tracing
the assembler code into the depths of the unknown than I am trying to
read the documentation to see if it actually tells me what I'm doing
wrong or how to do what I know I want to do. I'm thankful for forums
like this one where you can usually get an answer or at least a good
suggestion.

On the one hand it's nice to have this kind of "ioctl" interface to
every format, object and class. Once you master an item's use, you can
really fine-tune what you do with it (provided what you want to do is
actually supported AND you can figure out how to do it). Shoot, in
many cases you have more switches, controls, buttons and options than
an astronaut. That's pretty cool when you think about it.

On the flipside, if you don't have an intimate understanding of the
nuances of not only the APIs but also the data formats and their
variances, grasping their use is like listening to a stuttering blind
man describe an elephant or swimming the English Channel filled with
oatmeal.

It reminds me a lot of GUI programming. GUI has its merits for sure,
but programs are inherently muddled with noisey, eclectic,
exception-laden code, and the learning curve is steep. That's pretty
much what I see in many of the samples. Until you've been neck deep in
it for a while, it's not intuitive.

For instance, segmenting an ASF file -- a chore I expected to be
relatively straight forward -- turned out to be a pretty formidable
task when I reflect back on it. Thankfully there was a sample that
helped a LOT. My current endeavor involves a WMP interface with no
sample, and the interface's behavior varies in undocumented ways with
different file formats.

Early on I spent a half day trying to "fix" the "weird" things when I
run my app in the debugger, such as first-chance exceptions when using
code exactly as documented. After surfing the net I found a form where
it was said this exception generation paradigm is "by design to
discourage hackers".... hmmmmm.... paranoia will destroy ya... plus it
needlessly wasted a lot of my precious time.

In any event, a simplified, consistent, high-level API layer hiding
implementation and need-to-know details would increase programmer
productivity and expedite time to market, a significant benefit for
programmers who want to make use of the SDK on a casual basis to do
slightly-customized things with multimedia.

The existing I-interfaces and detailed structures give the multimedia
power-programmers most of the functionality they need to get neck deep
into the bowels of the whale and perform the exceptional, specialized
feats of magic that make us all go "WOW!"

So my 2-cent "newbie" observation on the complexities of the SDKs:
Dragonslaying is all well and good and a nice challenge, plus it feels
really great when you win; but sometimes it gets in the way of
accomplishing something useful in a short amount of time.

your mileage may vary with usage....

.

Relevant Pages

  • Re: I cant believe how complex this Format SDK is...
    ... Programming in general is never considered a breeze, ... provides me with an unbiased perspective on the docs and APIs. ... Overall I think the documentation is reasonably good, ... run my app in the debugger, such as first-chance exceptions when using ...
    (microsoft.public.windowsmedia.sdk)
  • Re: Whats Forth like?
    ... The second is that layering of code into APIs causes the programmer to have a narrowed focus on the APIs instead of a larger focus on the system as a whole. ... Of course in C, this documentation of intent is also read by the compiler, and it uses that information to validate that my intent is maintained and to generate better code. ...
    (comp.lang.forth)
  • Re: Q) CCombobox only displays one item.
    ... you specify forms using XAML. ... The documentation is probably being written by the person who is documenting Manifest ... time with a tree view data bound to an internal class, ... because the next thing the programmer needed to do was trivial in MFC ...
    (microsoft.public.vc.mfc)
  • Re: Should I use "if" or "try" (as a matter of speed)?
    ... Joel Spolsky might be a great C++ programmer, ... arguments about exceptions do not hold in Python. ...
    (comp.lang.python)
  • Re: docs patch: dicts and sets
    ... programmer will bring and apply his or her understanding ... nowhere in the "file" object documentation ... expectation based on previous experience with computers. ... While I treat opinions from Python ...
    (comp.lang.python)