flac dev - Jan 2007 - FLAC docs (was: Is FLAC fully cooked for OS X yet?)

On Jan 2, 2007, at 1:56 PM, Josh Coalson wrote:
>> OK, so I've been trying for a day now to get FLAC implementation in
>> our apps. Suffice it to say that due to the "interesting"
>> documentation [...]
>
> could you elaborate?
Well, I've just never seen anything like it before. There's a step- 
through, to be sure, but I got more information out of the headers  
than the actual online stuff, which seemed very intra-linked, very,  
shall we say - generated automatically...

I'm used to Apple's documentation, which is very clean and clear.  
This seemed a little overkill - lists of functions, lists of headers,  
lists of classes, alphabetically (even though 99% of them all start  
with FLAC__), etc. It seemed a little "too much" where it looks like  
it could  be a lot simpler - the API isn't really as complex as it  
looks like at first glance...

Ev
Technical Knowledge Officer
Head Programmer/Designer
Audiofile Engineering

http://www.audiofile-engineering.com/




-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://lists.xiph.org/pipermail/flac-dev/attachments/20070102/ad46a061/attachment.htm

--- Evan Olcott <ev@audiofile-engineering.com>
wrote:
> 
> On Jan 2, 2007, at 1:56 PM, Josh Coalson wrote:
> 
> >> OK, so I've been trying for a day now to get FLAC
implementation
> in
> >> our apps. Suffice it to say that due to the
"interesting"
> >> documentation [...]
> >
> > could you elaborate?
> 
> Well, I've just never seen anything like it before. There's a step-
> through, to be sure, but I got more information out of the headers  
> than the actual online stuff, which seemed very intra-linked, very,  
> shall we say - generated automatically...
> 
> I'm used to Apple's documentation, which is very clean and clear.  
> This seemed a little overkill - lists of functions, lists of headers,
>  
> lists of classes, alphabetically (even though 99% of them all start  
> with FLAC__), etc. It seemed a little "too much" where it looks
like
> 
> it could  be a lot simpler - the API isn't really as complex as it  
> looks like at first glance...
yes, the API docs are generated from headers by doxygen, and I
personally don't find a lot of the sections on the top navbar useful
except as an index... BUT it does have quite a lot of human-written
text in it.  (libFLAC is ~40% comments by weight which is unusually
high.)  it's best to start right at the top
http://flac.sourceforge.net/api/
and move down into the detailed modules, e.g.
http://flac.sourceforge.net/api/modules.html ->
http://flac.sourceforge.net/api/group__flac__decoder.html ->
http://flac.sourceforge.net/api/group__flac__stream__decoder.html

can you point to some apple docs which you like?  a lot of the
things I tried to find out about (like quicktime) either had
obsolete or inadequate info (but they were human-written) or
javadoc shells.  I hear from other developers that their docs
in the old days were much better.

if you're talking about the interconnectedness of the non-API
stuff (starting at http://flac.sourceforge.net/documentation.html)
it used to be more of a straight-through read, which I prefer too,
but the feedback I get is that most people want a more direct
route to solving their specific problem, so I reorganized it that
way.

Josh


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com

On Jan 2, 2007, at 4:02 PM, Josh Coalson wrote:
> can you point to some apple docs which you like?  a lot of the
> things I tried to find out about (like quicktime) either had
> obsolete or inadequate info (but they were human-written) or
> javadoc shells.  I hear from other developers that their docs
> in the old days were much better.
Naw, the documentation for Cocoa is fantastic. Very clean, easy to  
find stuff.
Here's an example (or even a starting point):
http://developer.apple.com/documentation/Cocoa/Reference/ 
ApplicationKit/Classes/NSApplication_Class/index.html
> if you're talking about the interconnectedness of the non-API
> stuff (starting at http://flac.sourceforge.net/documentation.html)
> it used to be more of a straight-through read, which I prefer too,
> but the feedback I get is that most people want a more direct
> route to solving their specific problem, so I reorganized it that
> way.
Totally understood.

Ev
Technical Knowledge Officer
Head Programmer/Designer
Audiofile Engineering

http://www.audiofile-engineering.com/




-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://lists.xiph.org/pipermail/flac-dev/attachments/20070103/b4fb43a7/attachment.htm

I realize that it entails more work, but I find that it is good to  
have both kinds of documentation, the straight-through read and the  
direct route.  I generally refer to those as Tutorial and Reference  
documents.  The Tutorial gives new developers all the concepts - in  
breadth, without necessarily going into depth on all calls.  The  
Reference is for seasoned developers who already understand the  
concepts, know which specific API they need, and want to read in- 
depth about all the details of a function call.

I think you could revive your old documentation which was a straight- 
through read, update it if it is now out-of-date, and add it to the  
documentation as a Tutorial.  But don't get rid of the ominous  
Reference documentation - those of us who are working on long-term  
projects need that, too.

Brian


On Jan 2, 2007, at 14:02, Josh Coalson wrote:
if you're talking about the interconnectedness of the non-API
stuff (starting at http://flac.sourceforge.net/documentation.html)
it used to be more of a straight-through read, which I prefer too,
but the feedback I get is that most people want a more direct
route to solving their specific problem, so I reorganized it that
way.

Josh