Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: "Stuart A. Malone" <email@hidden>
- Date: Fri, 8 Jul 2005 13:32:31 -0400
On Jul 8, 2005, at 11:34 AM, George Warner wrote:
I've been looking for a more informal format that our current
technote &
Q&A's. Perhaps I could do a K&B via our Q&A format... ;-)
Well, I guess I'll chime in with my own opinion...
For me, the problem isn't that there aren't enough informal channels
for developer information, it's that there are too many. Developer
information is spread across too many different documents, in too
many different formats. I'd far prefer a single monolithic
documentation set that was continuously improved and evolving, to a
more static documentation set that is surrounded by hundreds of notes
and addenda.
I'll give you a concrete example. We're adding an alarm feature to
our application, and we want to be able to play a sound when the
alarm goes off. We also want our customers to be able to use their
own sound files (MP3, AAC, etc.) as alarm sounds.
I have enough experience with Macintosh programming to know that my
options are probably Sound Manager (deprecated), QuickTime (complex),
Core Audio (also complex), or NSSound. NSSound looks like the
simplest solution, even though we're writing a Carbon application. I
look at the NSSound Overview in the "Introduction to Sound" article
and immediately see:
NSSound supports the following file and data formats:
File Formats:
AIFF
WAV
NeXT SND
So not too surprisingly, this leads me to believe that NSSound can't
play MP3 or AAC files and I start looking for another solution to the
problem.
Well, while doing internet-wide Google searches for another solution,
I stumble across a Technical Q&A QA1335 on the relative performance
of NSSound and NSMovie that casually mentions:
While NSSound supports any audio encodings and file formats that
QuickTime
does (as it still uses QuickTime for certain things), as of Mac
OS X 10.3
NSSound can also use CoreAudio for playback giving you a more
flexible class
to work with.
What's this? NSSound can play any format that QuickTime supports?
Since when? And why isn't this mentioned in the NSSound documentation?
In my opinion, Technical Q&A 1335 shouldn't exist at all. It would be
better if the NSSound Overview simply stated that "Starting with Mac
OS X 10.x, NSSound is also able to play any file formats supported by
QuickTime." And the NSMovie documentation should state that "As of
Mac OS X 10.3, the NSSound class has been enhanced to use Core Audio
for more efficient playback of certain sound formats. We recommend
using NSSound rather than NSMovie for audio-only playback."
I would like to see the documentation team at Apple be more focused
on making it easy for DTS and the engineers to keep the primary
documentation up-to-date. DTS should be able to drop an email to the
documentation team saying "we recommend using NSSound rather than
NSMovie for audio-only playback", and that should get edited into the
primary documentation for NSMovie and pushed out to the Apple web
site at the next site update, preferably within a day or two. There
really shouldn't be any need for engineers to create "a more informal
format" for issuing information to developers.
Sure, there might still be a place for short articles to notify
developers of significant changes to the primary documentation. And
the RSS feeds are a good way to let developers know about these
changes. But short articles, technotes, and addenda are no
substitute for keeping the main documentation up-to-date.
Best wishes,
--Stuart A. Malone
Llamagraphics, Inc.
Makers of Life Balance personal coaching software
http://www.llamagraphics.com/
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden