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
_______________________________________________
Flac-dev mailing list
Flac-dev@xiph.org
http://lists.xiph.org/mailman/listinfo/flac-dev
