[Flac-dev] Re: FLAC docs (was: Is FLAC fully cooked for OS X yet?)

[Brian Willoughby]

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